New-PSSession

Создает постоянное подключение к локальному или удаленному компьютеру.

Синтаксис

New-PSSession
   [[-ComputerName] <String[]>]
   [-Credential <PSCredential>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ConfigurationName <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-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
   -Credential <PSCredential>
   [-Name <String[]>]
   [-ConfigurationName <String>]
   [-VMId] <Guid[]>
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]
New-PSSession
   -Credential <PSCredential>
   [-Name <String[]>]
   [-ConfigurationName <String>]
   -VMName <String[]>
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]
New-PSSession
   [[-Session] <PSSession[]>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]
New-PSSession
   [-Name <String[]>]
   [-ConfigurationName <String>]
   -ContainerId <String[]>
   [-RunAsAdministrator]
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]

Описание

Командлет New-PSSession создает сеанс PowerShell (PSSession) на локальном или удаленном компьютере. При создании PSSession PowerShell устанавливает постоянное подключение к удаленному компьютеру.

Используйте PSSession для выполнения нескольких команд, которые совместно используют данные, например функцию или значение переменной. Чтобы выполнить команды в PSSession, используйте Invoke-Command командлет. Чтобы использовать PSSession для взаимодействия непосредственно с удаленным компьютером, используйте Enter-PSSession командлет. Дополнительные сведения см. в about_PSSessions.

Команды можно выполнять на удаленном компьютере без создания PSSession с помощью параметров Enter-PSSession ComputerName илиInvoke-Command. При использовании параметра ComputerName PowerShell создает временное соединение, которое используется для команды и затем закрывается.

Примеры

Пример 1. Создание сеанса на локальном компьютере

$s = New-PSSession

Эта команда создает новую psSession на локальном компьютере и сохраняет PSSession в переменной$s.

Теперь этот PSSession можно использовать для выполнения команд на локальном компьютере.

Пример 2. Создание сеанса на удаленном компьютере

$Server01 = New-PSSession -ComputerName Server01

Эта команда создает новую psSession на компьютере Server01 и сохраняет ее в переменной $Server01 .

При создании нескольких объектов PSSession назначьте их переменным с полезными именами. Это поможет вам управлять объектами PSSession в последующих командах.

Пример 3. Создание сеансов на нескольких компьютерах

$s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03

Эта команда создает три объекта PSSession , по одному на каждом из компьютеров, указанных параметром ComputerName .

Команда использует оператор назначения (=) для назначения новых объектов PSSession переменным: $s1, , $s2$s3. Он назначает серверу 01 PSSession , серверу 02 PSSession$s2$s1и серверу 03 PSSession .$s3

При назначении нескольких объектов в ряд переменных PowerShell назначает каждому объекту переменную в ряде соответственно. Если объектов больше, чем переменных, все оставшиеся объекты назначаются последней переменной. Если есть больше переменных, чем объекты, остальные переменные пусты ($null).

Пример 4. Создание сеанса с указанным портом

New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12

Эта команда создает новую службу PSSession на компьютере Server01, который подключается к порту 8081 сервера и использует протокол SSL. Новая конфигурация PSSession использует альтернативную конфигурациюE12сеанса.

Прежде чем задать порт, необходимо настроить прослушиватель службы удаленного управления Windows для прослушивания порта 8081 на удаленном компьютере. Дополнительные сведения см. в описании параметра Port.

Пример 5. Создание сеанса на основе существующего сеанса

New-PSSession -Session $s -Credential Domain01\User01

Эта команда создает PSSession с теми же свойствами, что и существующее PSSession. Этот формат команды можно использовать, если ресурсы существующей службы PSSession исчерпаны, а для разгрузки некоторых требований требуется новая служба PSSession.

Команда использует параметр сеансаNew-PSSession для указания psSession , сохраненного в переменной $s . Он использует учетные данные Domain1\Admin01 пользователя для выполнения команды.

Пример 6. Создание сеанса с глобальным область в другом домене

$global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01

В этом примере показано, как создать PSSession с глобальным область на компьютере в другом домене.

По умолчанию объекты PSSession, созданные в командной строке, создаются с локальными область и объектами PSSession, созданными в скрипте, имеют область скрипта.

Чтобы создать PSSession с глобальным область, создайте новую версию PSSession, а затем сохраните PSSession в переменной, приведение к глобальной область. В этом случае $s переменная приводится к глобальному область.

Команда использует параметр ComputerName, чтобы указать удаленный компьютер. Так как компьютер находится в домене, отличном от учетной записи пользователя, полное имя компьютера указывается вместе с учетными данными пользователя.

Пример 7. Создание сеансов для многих компьютеров

$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50

Эта команда создает PSSession на каждом из 200 компьютеров, перечисленных в Servers.txt файле, и сохраняет результирующий psSession в переменной$rs. Объекты PSSession имеют ограничение 50регулирования.

Этот формат команды можно использовать, если имена компьютеров хранятся в базе данных, электронной таблице, текстовом файле или другом формате, преобразуемом в текст.

Пример 8. Создание сеанса с помощью URI

$s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01

Эта команда создает PSSession на компьютере Server01 и сохраняет его в переменной $s . Он использует параметр URI для указания транспортного протокола, удаленного компьютера, порта и альтернативной конфигурации сеанса. Он также использует параметр Credential для указания учетной записи пользователя, которая имеет разрешение на создание сеанса на удаленном компьютере.

Пример 9. Запуск фонового задания в наборе сеансов

$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
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.

Дополнительные сведения о фоновых заданиях PowerShell см. в about_Jobs и about_Remote_Jobs.

Пример 10. Создание сеанса для компьютера с помощью URI

New-PSSession -ConnectionURI https://management.exchangelabs.com/Management

Эта команда создает объекты PSSession , которые подключаются к компьютеру, указанному URI вместо имени компьютера.

Пример 11. Создание параметра сеанса

$so = New-PSSessionOption -SkipCACheck
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. По умолчанию PowerShell не перенаправляет подключения, но этот параметр можно использовать для перенаправления подключения.

Можно также ограничить количество перенаправлений соединения, изменив значение параметра сеанса MaximumConnectionRedirectionCount. Используйте параметр MaximumRedirection командлета New-PSSessionOption или задайте свойство Maximum Подключение ionRedirectionCount переменной $PSSessionOption предпочтения. Значение по умолчанию — 5.

Type:SwitchParameter
Position:Named
Default value:False
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
  • Negotiate
  • NegotiateWithImplicitCredential

Значение по умолчанию — Default.

Дополнительные сведения о значениях этого параметра см. в разделе "Перечисление AuthenticationMechanism".

Внимание

Проверка подлинности поставщика поддержки безопасности учетных данных (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 команду на диске 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.

Чтобы включить локальный компьютер в значение параметра 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) схемы: http://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>

Значение по умолчанию определяется следующим образом.

http://localhost:5985/WSMAN

Если не указать параметр ConnectionURI, можно использовать параметры UseSSL, ComputerName, Port и ApplicationName для указания значения ConnectionURI.

Допустимые значения для сегмента транспорта URI — HTTP и HTTPS. Если указать универсальный код ресурса (URI) подключения с сегментом транспорта, но не указать порт, сеанс создается с помощью портов стандартов: 80 для HTTP и 443 HTTPS. Чтобы использовать порты по умолчанию для удаленного взаимодействия PowerShell, укажите порт 5985 для HTTP или 5986 HTTPS.

Если целевой компьютер перенаправляет подключение к другому URI, PowerShell запрещает перенаправление, если в команде не используется параметр AllowRedirection .

Type:Uri[]
Aliases:URI, CU
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-ContainerId

Задает массив идентификаторов контейнеров. Этот командлет запускает интерактивный сеанс с каждым из указанных контейнеров. docker ps Используйте команду, чтобы получить список идентификаторов контейнеров. Дополнительные сведения см. в справке для команды docker ps .

Type:String[]
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Credential

Указывает учетную запись пользователя, которая имеет разрешение на выполнение этого действия. По умолчанию используется текущий пользователь.

Введите имя пользователя, например User01 или Domain01\User01или введите объект PSCredential , созданный командлетом Get-Credential . Если ввести имя пользователя, вам будет предложено ввести пароль.

Учетные данные хранятся в объекте PSCredential , а пароль хранится как SecureString.

Примечание.

Дополнительные сведения о защите данных SecureString см. в разделе "Как безопасна Защита SecureString?".

Type:PSCredential
Position:Named
Default value:Current user
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-EnableNetworkAccess

Указывает, что этот командлет добавляет интерактивный маркер безопасности в сеансы обратного цикла. Интерактивный маркер позволяет выполнять в петлевом сеансе команды, которые получают данные с других компьютеров. Например, можно выполнить команду в сеансе, который копирует XML-файлы с удаленного компьютера на локальный.

Сеанс обратного цикла — это сеанс PSSession , который возникает и заканчивается на том же компьютере. Чтобы создать сеанс обратного цикла, опустите параметр ComputerName или задайте для нее значение dot (.), localhostили имя локального компьютера.

По умолчанию этот командлет создает сеансы обратного цикла с помощью сетевого маркера, который может не предоставить достаточно разрешений для проверки подлинности на удаленных компьютерах.

Параметр EnableNetworkAccess действует только в петлевых сеансах. Если при создании сеанса на удаленном компьютере используется EnableNetworkAccess , команда завершается успешно, но параметр игнорируется.

Вы также можете включить удаленный доступ в сеансе обратного цикла с помощью CredSSP значения параметра проверки подлинности, который делегирует учетные данные сеанса другим компьютерам.

Чтобы защитить компьютер от вредоносного доступа, отключенные сеансы цикла с интерактивными маркерами, созданными с помощью параметра EnableNetworkAccess , можно повторно подключиться только с компьютера, на котором был создан сеанс. Отключенные сеансы, использующие проверку подлинности CredSSP, можно повторно подключить с других компьютеров. Дополнительные сведения см. в разделе Disconnect-PSSession.

Этот параметр появился в PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
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

-RunAsAdministrator

Указывает, что PSSession выполняется от имени администратора.

Type:SwitchParameter
Position:Named
Default value:False
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 шифрует все содержимое PowerShell, передаваемое по сети. Параметр UseSSL обеспечивает дополнительную защиту, которая отправляет данные через HTTPS-подключение вместо HTTP-подключения.

Если вы используете этот параметр, но SSL недоступен на порту, который используется для команды, команда завершается ошибкой.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-VMId

Задает массив идентификаторов виртуальных машин. Этот командлет запускает интерактивный сеанс PowerShell Direct с каждой из указанных виртуальных машин. Дополнительные сведения см. в статье "Автоматизация и управление виртуальными машинами" с помощью PowerShell.

Используйте Get-VM для просмотра виртуальных машин, доступных на узле Hyper-V.

Type:Guid[]
Aliases:VMGuid
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-VMName

Указывает массив имен виртуальных машин. Этот командлет запускает интерактивный сеанс PowerShell Direct с каждой из указанных виртуальных машин. Дополнительные сведения см. в статье "Автоматизация и управление виртуальными машинами" с помощью PowerShell.

Используйте Get-VM для просмотра виртуальных машин, доступных на узле Hyper-V.

Type:String[]
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

Входные данные

String

Вы можете передать строку в этот командлет.

System.URI

Вы можете передать универсальный код ресурса (URI) в этот командлет.

PSSession

Объект сеанса можно передать в этот командлет.

Выходные данные

PSSession

Примечания

Windows PowerShell включает следующие псевдонимы для New-PSSession:

  • nsn

  • Этот командлет использует инфраструктуру удаленного взаимодействия PowerShell. Чтобы использовать этот командлет, локальный компьютер и все удаленные компьютеры должны быть настроены для удаленного взаимодействия PowerShell. Дополнительные сведения см. в about_Remote_Requirements.

  • Чтобы создать PSSession на локальном компьютере, запустите PowerShell с параметром запуска от имени администратора .

  • Завершив работу с PSSession, используйте Remove-PSSession командлет для удаления PSSession и освобождения его ресурсов.