New-PSSession
Создает постоянное подключение к локальному или удаленному компьютеру.
Синтаксис
New-PSSession
[[-ComputerName] <String[]>]
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-ApplicationName <String>]
[-ThrottleLimit <Int32>]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]New-PSSession
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ConfigurationName <String>]
[-ThrottleLimit <Int32>]
[-ConnectionUri] <Uri[]>
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]New-PSSession
[[-Session] <PSSession[]>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ThrottleLimit <Int32>]
[<CommonParameters>]Описание
Командлет New-PSSession создает сеанс Windows PowerShell (PSSession) на локальном или удаленном компьютере. При создании PSSession Windows PowerShell устанавливает постоянное подключение к удаленному компьютеру.
Используйте PSSession для выполнения нескольких команд, которые совместно используют данные, например функцию или значение переменной. Чтобы выполнить команды в PSSession, используйте командлет Invoke-Command. Чтобы использовать PSSession для прямого взаимодействия с удаленным компьютером, используйте командлет Enter-PSSession. Дополнительные сведения см. в разделе about_PSSessions (https://go.microsoft.com/fwlink/?LinkID=135181).
Команды можно выполнять на удаленном компьютере без создания PSSession с помощью параметров ComputerNameкоманд Enter-PSSession или Invoke-Command. При использовании параметра ComputerName Windows PowerShell создает временное подключение, используемое для выполнения команды, которое затем разрывается.
Примеры
Пример 1. Create сеанса на локальном компьютере
PS C:\> $s = New-PSSessionЭта команда создает новый сеанс PSSession на локальном компьютере и сохраняет его в переменной $s.
Теперь эту psSession можно использовать для выполнения команд на локальном компьютере.
Пример 2. Create сеанса на удаленном компьютере
PS C:\> $Server01 = New-PSSession -ComputerName Server01Эта команда создает новый сеанс PSSession на компьютере Server01 и сохраняет его в переменной $Server 01.
При создании нескольких объектов PSSession назначьте их переменным с полезными именами. Это поможет управлять объектами PSSession в последующих командах.
Пример 3. сеансы Create на нескольких компьютерах
PS C:\> $s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03Эта команда создает три объекта PSSession , по одному на каждом из компьютеров, указанных параметром ComputerName .
Команда использует оператор присваивания (=) для назначения новых объектов PSSession переменным: $s 1, $s 2, $s 3. Он назначает сеанс PSSession Server01 $s 1, server02 PSSession — $s 2, а server03 PSSession — $s 3.
При назначении нескольких объектов последовательности переменных Windows PowerShell присваивает каждый объект переменной в ряде соответственно. Если объектов больше, чем переменных, все оставшиеся объекты назначаются последней переменной. Если переменных больше, чем объектов, оставшиеся переменные остаются пустыми (null).
Пример 4. Create сеанса с указанным портом
PS C:\> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12Эта команда создает новый psSession на компьютере Server01, который подключается к порту сервера 8081 и использует протокол SSL. В новом сеансе PSSession используется альтернативная конфигурация сеанса E12.
Прежде чем задать порт, необходимо настроить прослушиватель службы удаленного управления Windows для прослушивания порта 8081 на удаленном компьютере. Дополнительные сведения см. в описании параметра Port.
Пример 5. Create сеанса на основе существующего сеанса
PS C:\> New-PSSession -Session $s -Credential Domain01\User01Эта команда создает PSSession с теми же свойствами, что и у существующего psSession. Этот формат команд можно использовать, когда ресурсы существующего сеанса PSSession исчерпаны и для разгрузки некоторых потребностей требуется новый сеанс PSSession .
Команда использует параметр Sessionобъекта New-PSSession для указания psSession, сохраненного в переменной $s. Она использует для выполнения команды учетные данные пользователя Domain1\Admin01.
Пример 6. Create сеанса с глобальным область в другом домене
PS C:\> $global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01В этом примере показано, как создать PSSession с глобальным область на компьютере в другом домене.
По умолчанию объекты PSSession, созданные в командной строке, создаются вместе с локальными область, а объекты PSSession, созданные в скрипте, имеют область скрипта.
Чтобы создать psSession с глобальным область, создайте новый psSession, а затем сохраните psSession в переменной, которая приводится к глобальному область. В данном случае переменная $s приведена к глобальной области.
Команда использует параметр ComputerName, чтобы указать удаленный компьютер. Поскольку компьютер находится в домене, отличном от учетной записи пользователя, полное имя компьютера указывается вместе с учетными данными пользователя.
Пример 7. сеансы Create для нескольких компьютеров
PS C:\> $rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50Эта команда создает PSSession на каждом из 200 компьютеров, перечисленных в файле Servers.txt, и сохраняет полученное psSession в переменной $rs. Для объектов PSSession ограничение регулирования равно 50.
Этот формат команды можно использовать, если имена компьютеров хранятся в базе данных, электронной таблице, текстовом файле или другом формате, преобразуемом в текст.
Пример 8. Create сеанса с помощью универсального кода ресурса (URI)
PS C:\> $s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01Эта команда создает PSSession на компьютере Server01 и сохраняет его в переменной $s. Он использует параметр URI для указания транспортного протокола, удаленного компьютера, порта и альтернативной конфигурации сеанса. Он также использует параметр Credential для указания учетной записи пользователя, которая имеет разрешение на создание сеанса на удаленном компьютере.
Пример 9. Запуск фонового задания в наборе сеансов
PS C:\> $s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJobЭти команды создают набор объектов PSSession , а затем выполняют фоновое задание в каждом из объектов PSSession .
Первая команда создает новый psSession на каждом из компьютеров, перечисленных в файле Servers.txt. Он использует командлет New-PSSession для создания PSSession. Значением параметра ComputerName является команда, которая использует командлет Get-Content для получения списка имен компьютеров из файла Servers.txt.
Команда использует параметр Credential для создания объектов PSSession , имеющих разрешение администратора домена, и использует параметр ThrottleLimit , чтобы ограничить команду 16 одновременными подключениями. Команда сохраняет объекты PSSession в переменной $s.
Вторая команда использует параметр AsJob командлета Invoke-Command для запуска фонового задания, которое выполняет Get-Process PowerShell команду в каждом из объектов PSSession в $s.
Дополнительные сведения о фоновых заданиях Windows PowerShell см. в разделах about_Jobs и about_Remote_Jobs.
Пример 10. Create сеанса для компьютера с помощью его URI
PS C:\> New-PSSession -ConnectionURI https://management.exchangelabs.com/ManagementЭта команда создает объекты PSSession , которые подключаются к компьютеру, указанному с помощью URI, а не имени компьютера.
Пример 11. Create параметр сеанса
PS C:\> $so = New-PSSessionOption -SkipCACheck
PS C:\> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01В этом примере показано, как создать объект параметра сеанса и использовать параметр SessionOption .
Первая команда использует командлет New-PSSessionOption, чтобы создать параметры сеанса. Полученный объект SessionOption сохраняется в переменной $so.
Вторая команда использует параметр в новом сеансе. Команда использует командлет New-PSSession для создания нового сеанса. Значение параметра SessionOption — это объект SessionOption в переменной $so.
Параметры
-AllowRedirection
Указывает, что этот командлет разрешает перенаправление этого подключения на альтернативный универсальный код ресурса (URI).
При использовании параметра ConnectionURI удаленный компьютер может вернуть инструкцию для перенаправления на другой URI. По умолчанию Windows PowerShell не перенаправляет подключения, но этот параметр можно использовать для перенаправления подключения.
Можно также ограничить количество перенаправлений соединение, изменив значение параметра сеанса MaximumConnectionRedirectionCount. Используйте параметр MaximumRedirection командлета New-PSSessionOption или задайте свойство MaximumConnectionRedirectionCount переменной предпочтения $PSSessionOption . Значение по умолчанию — 5.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ApplicationName
Определяет сегмент имени приложения в URI соединения. Используйте этот параметр, чтобы указать имя приложения, если в команде не используется параметр ConnectionURI.
По умолчанию используется значение привилегированной переменной $PSSessionApplicationName на локальном компьютере. Если привилегированная переменная не определена, значение по умолчанию — WSMAN. Это значение подходит для большинства случаев Дополнительные сведения см. в разделе about_Preference_Variables.
Служба удаленного управления Windows (WinRM) использует имя приложения для выбора прослушивателя для обслуживания запроса на подключение. Значение этого параметра должно совпадать со значением свойства URLPrefix прослушивателя на удаленном компьютере.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Authentication
Задает механизм, используемый при проверке подлинности учетных данных пользователя. Допустимые значения для этого параметра:
- Default
- Basic
- Credssp
- Digest (дайджест)
- Kerberos
- Согласование
- NegotiateWithImplicitCredential
Значение по умолчанию — Default.
Дополнительные сведения о значениях этого параметра см. в разделе Перечисление AuthenticationMechanism в библиотеке MSDN.
Внимание! Проверка подлинности поставщика поддержки безопасности учетных данных (CredSSP), при которой учетные данные пользователя передаются на удаленный компьютер для проверки подлинности, предназначена для команд, требующих проверки подлинности в нескольких ресурсах, таких как доступ к удаленному сетевому ресурсу. Этот механизм повышает риск безопасности удаленной операции. Если удаленный компьютер скомпрометирован, учетные данные, передаваемые ему, могут использоваться для управления сетевым сеансом.
| Type: | AuthenticationMechanism |
| Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CertificateThumbprint
Задает цифровой сертификат с открытым ключом (X509) учетной записи пользователя, который располагает разрешением для выполнения этого действия. Введите отпечаток сертификата.
Сертификаты используются при проверке подлинности на основе сертификата клиента. Они могут сопоставляться только с учетными записями локальных пользователей и не работают с учетными записями доменов.
Для получения сертификата воспользуйтесь командой Get-Item или Get-ChildItem в Windows PowerShell на диске Cert:.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ComputerName
Задает массив имен компьютеров. Этот командлет создает постоянное подключение (PSSession) к указанному компьютеру. Если ввести несколько имен компьютеров, New-PSSession создаст несколько объектов PSSession , по одному для каждого компьютера. По умолчанию это локальный компьютер.
Введите имя NetBIOS, IP-адрес или полное доменное имя одного или нескольких удаленных компьютеров. Чтобы указать локальный компьютер, введите имя компьютера, localhost или точку (.). Если компьютер находится в другом домене, отличном от домена пользователя, полное доменное имя является обязательным. Вы также можете передать имя компьютера в кавычки в New-PSSession.
Чтобы использовать IP-адрес в значении параметра ComputerName , команда должна включать параметр Credential . Кроме того, компьютер должен быть настроен для транспорта HTTPS или IP-адрес удаленного компьютера должен быть включен в список TrustedHosts службы WinRM на локальном компьютере. Инструкции по добавлению имени компьютера в список TrustedHosts см. в разделе Добавление компьютера в список доверенных узлов в about_Remote_Troubleshooting (https://go.microsoft.com/fwlink/?LinkID=135188).
Чтобы включить локальный компьютер в значение параметра ComputerName, запустите Windows PowerShell с помощью параметра Запуск от имени администратора.
| Type: | String[] |
| Aliases: | Cn |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ConfigurationName
Указывает конфигурацию сеанса, используемую для нового PSSession.
Введите имя конфигурации или полное имя ресурса (URI) для конфигурации сеанса.
Если указать только имя конфигурации, предопределен следующий универсальный код ресурса (URI) схемы: https://schemas.microsoft.com/PowerShell.
Конфигурация сеанса для сеанса размещается на удаленном компьютере. Если указанной конфигурации сеанса нет на удаленном компьютере, команда завершается ошибкой.
Значение по умолчанию — это значение привилегированной переменной $PSSessionConfigurationName на локальном компьютере. Если эта привилегированная переменная не определена, значением по умолчанию является Microsoft.PowerShell. Дополнительные сведения см. в разделе about_Preference_Variables.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ConnectionUri
Указывает универсальный код ресурса (URI), определяющий конечную точку подключения для сеанса. Значение URI должно быть указано полностью. Строка имеет следующий формат:
<Transport>://<ComputerName>:<Port>/<ApplicationName>
Значение по умолчанию определяется следующим образом.
https://localhost:5985/WSMAN
Если не указывать ConnectionURI, можно использовать параметры UseSSL, ComputerName, Port и ApplicationName для задания значений ConnectionURI.
Допустимые значения для сегмента транспорта URI — HTTP и HTTPS. Если указать URI подключения с сегментом Transport, но не указать порт, сеанс будет создан со стандартными портами: 80 для HTTP и 443 для HTTPS. Чтобы использовать порты по умолчанию для удаленного взаимодействия Windows PowerShell, укажите порт 5985 для протокола HTTP и 5986 для протокола HTTPS.
Если конечный компьютер перенаправляет соединение на другой URI, Windows PowerShell предотвращает перенаправление, если в команде не указать параметр AllowRedirection.
| Type: | Uri[] |
| Aliases: | URI, CU |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Credential
Указывает учетную запись пользователя с разрешением на выполнение этого действия. По умолчанию используется текущий пользователь.
Введите имя пользователя, например User01, Domain01\User01 или User@Domain.com, или введите объект PSCredential , например, возвращенный командлетом Get-Credential.
При вводе имени пользователя этот командлет запрашивает пароль.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-EnableNetworkAccess
Указывает, что этот командлет добавляет интерактивный маркер безопасности в сеансы замыкания на себя. Интерактивный маркер позволяет выполнять в петлевом сеансе команды, которые получают данные с других компьютеров. Например, можно выполнить команду в сеансе, который копирует XML-файлы с удаленного компьютера на локальный.
Сеанс замыкания на себя — это сеанс PSSession , который начинается и заканчивается на том же компьютере. Чтобы создать сеанс замыкания на себя, опустите параметр ComputerName или задайте для его значения точку (.), localhost или имя локального компьютера.
По умолчанию этот командлет создает сеансы замыкания на себя с помощью сетевого маркера, который может не предоставлять достаточных разрешений для проверки подлинности на удаленных компьютерах.
Параметр EnableNetworkAccess действует только в петлевых сеансах. Если при создании сеанса на удаленном компьютере используется enableNetworkAccess , команда будет выполнена успешно, но параметр игнорируется.
Вы также можете включить удаленный доступ в сеансе замыкания на себя, используя значение CredSSP параметра Authentication , которое делегирует учетные данные сеанса другим компьютерам.
Чтобы защитить компьютер от вредоносного доступа, отключенные сеансы замыкания на себя, имеющие интерактивные маркеры, созданные с помощью параметра EnableNetworkAccess , можно повторно подключить только к компьютеру, на котором был создан сеанс. Отключенные сеансы, использующие проверку подлинности CredSSP, можно повторно подключить с других компьютеров. Дополнительные сведения см. в разделе о Disconnect-PSSession.
Этот параметр впервые появился в Windows PowerShell 3.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Name
Указывает понятное имя для PSSession.
Имя можно использовать для ссылки на PSSession при использовании других командлетов, таких как Get-PSSession и Enter-PSSession. Имя не обязательно должно быть уникальным для компьютера или текущего сеанса.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Port
Задает сетевой порт на удаленном компьютере, используемый для данного соединения. Для подключения к удаленному компьютеру требуется, чтобы он прослушивал порт, используемый соединением. По умолчанию используются порты 5985 ( порт WinRM для HTTP), и 5986 , который является портом WinRM для HTTPS.
Перед использованием другого порта необходимо настроить прослушиватель WinRM на удаленном компьютере для прослушивания через этот порт. Для настройки прослушивателя используйте следующие команды:
1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}
Не используйте параметр Port, если этого можно избежать. Настройка порта в команде применяется ко всем компьютерам или сеансам, на которых выполняется команда. Альтернативный порт может помешать выполнению команды на всех компьютерах.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Session
Задает массив объектов PSSession , которые этот командлет использует в качестве модели для нового PSSession. Этот параметр создает новые объекты PSSession , которые имеют те же свойства, что и указанные объекты PSSession .
Введите переменную, содержащую объекты PSSession , или команду, которая создает или получает объекты PSSession , например New-PSSession или команду Get-PSSession.
Результирующие объекты PSSession имеют то же имя компьютера, имя приложения, универсальный код ресурса (URI) подключения, порт, имя конфигурации, ограничение регулирования и значение SSL, что и оригиналы, но имеют другое отображаемое имя, идентификатор и идентификатор экземпляра (GUID).
| Type: | PSSession[] |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-SessionOption
Задает дополнительные параметры для сеанса. Введите объект SessionOption, например объект, созданный с помощью командлета New-PSSessionOption, или хэш-таблицу, где ключи — это имена параметров сеанса, а значения — это значения параметров сеанса.
Значения по умолчанию для параметров определяются значением привилегированной переменной $PSSessionOption, если оно задано. В противном случае значения по умолчанию задаются параметрами, указанными в конфигурации сеанса.
Значения параметров сеанса имеют приоритет над значениями по умолчанию, заданными в переменной $PSSessionOption и конфигурации сеанса. Однако они не имеют приоритет над максимальными значениями, квотами и ограничениями, заданными в конфигурации сеанса.
Описание параметров сеанса, которые включают значения по умолчанию, см. в разделе New-PSSessionOption. Сведения о переменной предпочтения $PSSessionOption см. в разделе about_Preference_Variables. Дополнительные сведения о конфигурациях сеансов см. в разделе about_Session_Configurations.
| Type: | PSSessionOption |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ThrottleLimit
Указывает максимальное число одновременных подключений, которые можно установить для запуска этой команды. Если этот параметр не указан или введено значение 0 (ноль), используется значение по умолчанию — 32.
Предел регулирования применяется только к текущему командлету, а не к сеансу или компьютеру.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseSSL
Указывает, что этот командлет использует протокол SSL для установки подключения к удаленному компьютеру. По умолчанию SSL не используется.
Протокол WS-Management шифрует все содержимое Windows PowerShell, передаваемое по сети. Параметр UseSSL обеспечивает дополнительную защиту, которая отправляет данные через HTTPS-подключение, а не через HTTP-подключение.
Если вы используете этот параметр, но SSL недоступен на порту, используемом для команды, команда завершается ошибкой.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Входные данные
System.String, System.URI, System.Management.Automation.Runspaces.PSSession
Вы можете передать строку, универсальный код ресурса (URI) или объект сеанса в этот командлет.
Выходные данные
Примечания
Этот командлет использует инфраструктуру удаленного взаимодействия Windows PowerShell. Для использования этого командлета локальный и удаленные компьютеры должно быть настроены для удаленного взаимодействия Windows PowerShell. Дополнительные сведения см. в разделе about_Remote_Requirements.
Чтобы создать PSSession на локальном компьютере, запустите Windows PowerShell с параметром Запуск от имени администратора.
Завершив работу с PSSession, используйте командлет Remove-PSSession, чтобы удалить psSession и освободить его ресурсы.