New-PSSession

Синтаксис

ComputerName (по умолчанию)

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>]

Uri

New-PSSession
    [-ConnectionUri] <Uri[]>
    [-Credential <PSCredential>]
    [-Name <String[]>]
    [-EnableNetworkAccess]
    [-ConfigurationName <String>]
    [-ThrottleLimit <Int32>]
    [-AllowRedirection]
    [-SessionOption <PSSessionOption>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [<CommonParameters>]

VMId

New-PSSession
    [-VMId] <Guid[]>
    -Credential <PSCredential>
    [-Name <String[]>]
    [-ConfigurationName <String>]
    [-ThrottleLimit <Int32>]
    [<CommonParameters>]

VMName

New-PSSession
    -Credential <PSCredential>
    -VMName <String[]>
    [-Name <String[]>]
    [-ConfigurationName <String>]
    [-ThrottleLimit <Int32>]
    [<CommonParameters>]

Session

New-PSSession
    [[-Session] <PSSession[]>]
    [-Name <String[]>]
    [-EnableNetworkAccess]
    [-ThrottleLimit <Int32>]
    [<CommonParameters>]

ContainerId

New-PSSession
    -ContainerId <String[]>
    [-Name <String[]>]
    [-ConfigurationName <String>]
    [-RunAsAdministrator]
    [-ThrottleLimit <Int32>]
    [<CommonParameters>]

UseWindowsPowerShellParameterSet

New-PSSession
    [-Name <String[]>]
    [-UseWindowsPowerShell]
    [<CommonParameters>]

SSHHost

New-PSSession
    [-HostName] <String[]>
    [-Name <String[]>]
    [-Port <Int32>]
    [-UserName <String>]
    [-KeyFilePath <String>]
    [-Subsystem <String>]
    [-ConnectingTimeout <Int32>]
    [-SSHTransport]
    [-Options <Hashtable>]
    [<CommonParameters>]

SSHHostHashParam

New-PSSession
    -SSHConnection <Hashtable[]>
    [-Name <String[]>]
    [<CommonParameters>]

Описание

Примеры

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

$s = New-PSSession

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

$Server01 = New-PSSession -ComputerName Server01

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

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

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

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

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

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

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

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

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

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

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

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

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

$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
Invoke-Command -Session $s -ScriptBlock {Get-Process powershell} -AsJob

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

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

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

$so = New-PSSessionOption -SkipCACheck
New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01

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

New-PSSession -HostName UserA@LinuxServer01

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

New-PSSession -HostName UserA@LinuxServer01:22 -KeyFilePath C:\<path>\userAKey_rsa

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

$sshConnections = @(
    @{
          HostName    = 'WinServer1'
          UserName    = 'domain\userA'
          KeyFilePath = 'C:\Users\UserA\id_rsa'
    }
    @{
        HostName    = 'UserB@LinuxServer5'
        KeyFilePath = 'C:\UserB\<path>\id_rsa'
    }
)
New-PSSession -SSHConnection $sshConnections

Пример 15. Создание нового сеанса с помощью параметров SSH

$options = @{
    Port=22
    User = 'UserB'
    Host = 'LinuxServer5'
}
New-PSSession -KeyFilePath '/Users/UserB/id_rsa' -Options $options

Параметры

-AllowRedirection

Указывает, что этот командлет разрешает перенаправление этого подключения к альтернативному универсальному идентификатору ресурса (URI).

При использовании параметра ConnectionURI удаленный целевой объект может вернуть инструкцию для перенаправления в другой универсальный код ресурса (URI). По умолчанию PowerShell не перенаправляет подключения, но этот параметр можно использовать для перенаправления подключения.

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

Свойства параметра

Наборы параметров

-ApplicationName

Определяет сегмент имени приложения в URI соединения. Используйте этот параметр, чтобы указать имя приложения, если в команде не используется параметр ConnectionURI.

Значение по умолчанию — это значение переменной предпочтения $PSSessionApplicationName на локальном компьютере. Если эта переменная предпочтения не определена, значение по умолчанию равно WSMAN. Это значение подходит для большинства использования. Дополнительные сведения см. в разделе about_Preference_Variables.

Служба WinRM использует имя приложения для выбора прослушивателя для обслуживания запроса на подключение. Значение этого параметра должно соответствовать значению свойства URLPrefix прослушивателя на удаленном компьютере.

Свойства параметра

Наборы параметров

-Authentication

Указывает механизм, используемый для проверки подлинности учетных данных пользователя. Допустимые значения для этого параметра:

• Default
• Basic
• Credssp
• Digest
• Kerberos
• Negotiate
• NegotiateWithImplicitCredential

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

Для получения дополнительной информации о значениях этого параметра см. перечисление AuthenticationMechanism.

Свойства параметра

Наборы параметров

-CertificateThumbprint

Указывает сертификат цифрового открытого ключа (X509) учетной записи пользователя, которая имеет разрешение на выполнение этого действия. Введите отпечаток пальца сертификата.

Сертификаты используются в аутентификации, основанной на клиентских сертификатах. Их можно сопоставить только с локальными учетными записями пользователей; Они не работают с учетными записями домена.

Чтобы получить сертификат, используйте Get-Item или Get-ChildItem команду на диске PowerShell Cert: .

Свойства параметра

Наборы параметров

-ComputerName

Задает массив имен компьютеров. Этот командлет создает постоянное подключение (PSSession) к указанному компьютеру. При вводе нескольких имен компьютеров New-PSSession создается несколько объектов PSSession , по одному для каждого компьютера. По умолчанию используется локальный компьютер.

Введите имя NetBIOS, IP-адрес или полное доменное имя одного или нескольких удаленных компьютеров. Чтобы указать локальный компьютер, введите имя компьютера, localhostили точку (.). Если компьютер находится в домене, отличном от пользователя, требуется полное доменное имя. Вы также можете передать имя компьютера в кавычки New-PSSession.

Чтобы использовать IP-адрес в значении параметра ComputerName, команда должна включать параметр Credential. Кроме того, компьютер должен быть настроен для транспорта HTTPS или IP-адрес удаленного компьютера должен быть включен в список WinRM TrustedHosts на локальном компьютере. Инструкции по добавлению имени компьютера в список TrustedHosts см. в разделе "Добавление компьютера в список доверенных узлов" в about_Remote_Troubleshooting.

Чтобы включить локальный компьютер в значение параметра ComputerName , запустите Windows PowerShell с помощью параметра запуска от имени администратора.

Свойства параметра

Наборы параметров

-ConfigurationName

Указывает конфигурацию сеанса, используемую для нового psSession.

Введите имя конфигурации или полный URI ресурса для конфигурации сеанса. Если указать только имя конфигурации, предопределен следующий URI схемы: http://schemas.microsoft.com/PowerShell.

Конфигурация сеанса для сеанса расположена на удаленном компьютере. Если указанная конфигурация сеанса не существует на удаленном компьютере, команда завершается ошибкой.

Значение по умолчанию — это значение переменной предпочтения $PSSessionConfigurationName на локальном компьютере. Если эта переменная предпочтения не задана, используется Microsoft.PowerShellзначение по умолчанию. Дополнительные сведения см. в разделе about_Preference_Variables.

Свойства параметра

Наборы параметров

-ConnectingTimeout

Указывает время в миллисекундах, разрешенное для завершения начального подключения SSH. Если подключение не завершено в течение указанного времени, возвращается ошибка.

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

Свойства параметра

Наборы параметров

-ConnectionUri

Задает универсальный код ресурса (URI), определяющий конечную точку подключения для сеанса. Универсальный код ресурса (URI) должен быть полностью определённым. Формат этой строки выглядит следующим образом:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

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

http://localhost:5985/WSMAN

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

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

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

Свойства параметра

Наборы параметров

-ContainerId

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

Свойства параметра

Наборы параметров

-Credential

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

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

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

Свойства параметра

Наборы параметров

-EnableNetworkAccess

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

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

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

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

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

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

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

Свойства параметра

Наборы параметров

-HostName

Задает массив имен компьютеров для подключения на основе Secure Shell (SSH). Это аналогично параметру ComputerName , за исключением того, что подключение к удаленному компьютеру выполняется с помощью SSH, а не Windows WinRM.

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

Свойства параметра

Наборы параметров

-KeyFilePath

Указывает путь к файлу ключа, используемый Secure Shell (SSH) для проверки подлинности пользователя на удаленном компьютере.

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

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

Свойства параметра

Наборы параметров

-Name

Указывает понятное имя PSSession.

Имя можно использовать для ссылки на PSSession при использовании других командлетов, таких как Get-PSSession и Enter-PSSession. Имя не обязательно должно быть уникальным для компьютера или текущего сеанса.

Свойства параметра

Наборы параметров

-Options

Указывает хэш-список параметров SSH, используемых при подключении к удаленному сеансу на основе SSH. Возможные параметры — это любые значения, поддерживаемые версией команды SSH на основе Unix.

Все значения, явно переданные параметрами, имеют приоритет над значениями, переданными в хэш-таблицы Options . Например, при использовании параметра Port переопределяется любая Port пара "ключ-значение", переданная в хэш-файл " Параметры ".

Свойства параметра

Наборы параметров

-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\>"}

Не используйте параметр порта , если вы не должны. Параметр порта в команде применяется ко всем компьютерам или сеансам, на которых выполняется команда. Альтернативный параметр порта может предотвратить выполнение команды на всех компьютерах.

Свойства параметра

Наборы параметров

-RunAsAdministrator

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

Свойства параметра

Наборы параметров

-Session

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

Введите переменную, содержащую объекты PSSession или команду, которая создает или получает объекты PSSession , например New-PSSession команду или Get-PSSession команду.

В результате объектов PSSession имеют то же имя компьютера, имя приложения, URI подключения, порт, имя конфигурации, ограничение регулирования и значение SSL, но они имеют другое отображаемое имя, идентификатор и идентификатор экземпляра (GUID).

Свойства параметра

Наборы параметров

-SessionOption

Задает дополнительные параметры сеанса. Введите объект SessionOption, например объект, создаваемый с помощью командлета New-PSSessionOption, или хэш-таблицу, в которой ключи являются именами вариантов сеанса, а значения — значениями параметров сеанса.

Значения по умолчанию для параметров определяются значением переменной предпочтения $PSSessionOption, если она задана. В противном случае значения по умолчанию устанавливаются параметрами, заданными в конфигурации сеанса.

Значения параметра сеанса имеют приоритет над значениями по умолчанию для сеансов, заданных в переменной предпочтения $PSSessionOption и в конфигурации сеанса. Однако они не имеют приоритета над максимальными значениями, квотами или ограничениями, установленными в конфигурации сеанса.

Описание параметров сеанса, включающих значения по умолчанию, см. New-PSSessionOption. Сведения о переменной предпочтения $PSSessionOption см. в about_Preference_Variables. Дополнительные сведения о конфигурациях сеансов см. в about_Session_Configurations.

Свойства параметра

Наборы параметров

-SSHConnection

Этот параметр принимает массив хэш-таблиц, где каждый хэш-файл содержит один или несколько параметров подключения, необходимых для установления подключения Secure Shell (SSH) (HostName, Port, UserName, KeyFilePath).

Параметры подключения хэш-кода совпадают с параметрами SSHHost .

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

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

Свойства параметра

Наборы параметров

-SSHTransport

Указывает, что удаленное подключение установлено с помощью Secure Shell (SSH).

По умолчанию PowerShell использует Windows WinRM для подключения к удаленному компьютеру. Этот коммутатор заставляет PowerShell использовать набор параметров HostName для установки удаленного подключения на основе SSH.

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

Свойства параметра

Наборы параметров

-Subsystem

Задает подсистему SSH, используемую для новой подсистемы PSSession.

Это указывает подсистему, используемую в целевом объекте, как определено в sshd_config. Подсистема запускает определенную версию PowerShell с предопределенными параметрами. Если указанная подсистема не существует на удаленном компьютере, команда завершается ошибкой.

Если этот параметр не используется, по умолчанию используется подсистема powershell .

Свойства параметра

Наборы параметров

-ThrottleLimit

Указывает максимальное количество одновременных подключений, которые можно установить для выполнения этой команды. Если этот параметр не указан или введите значение 0 (ноль), используется значение по умолчанию 32.

Ограничение регулирования применяется только к текущей команде, а не к сеансу или к компьютеру.

Свойства параметра

Наборы параметров

-UserName

Указывает имя пользователя для учетной записи, используемой для создания сеанса на удаленном компьютере. Метод проверки подлинности пользователя зависит от настройки Secure Shell (SSH) на удаленном компьютере.

Если SSH настроен для базовой проверки подлинности паролей, вам будет предложено ввести пароль пользователя.

Если SSH настроен для проверки подлинности пользователя на основе ключей, то путь к файлу ключа можно указать с помощью параметра KeyFilePath , и вам не будет предложено ввести пароль. Обратите внимание, что если файл ключа пользователя клиента находится в известном расположении SSH, параметр KeyFilePath не нужен для проверки подлинности на основе ключей, а проверка подлинности пользователя выполняется автоматически на основе имени пользователя. Дополнительные сведения см. в документации по SSH о проверке подлинности пользователей на основе ключей.

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

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

Свойства параметра

Наборы параметров

-UseSSL

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

WS-Management шифрует все содержимое PowerShell, передаваемое по сети. Параметр UseSSL обеспечивает дополнительную защиту, которая отправляет данные через HTTPS-подключение вместо HTTP-подключения.

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

Свойства параметра

Наборы параметров

-UseWindowsPowerShell

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

Свойства параметра

Наборы параметров

-VMId

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

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

Свойства параметра

Наборы параметров

-VMName

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

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

Свойства параметра

Наборы параметров

CommonParameters

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

String

System.URI

PSSession

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

PSSession

Примечания

Связанные ссылки

• Connect-PSSession
• Disconnect-PSSession
• Enter-PSSession
• Выход из PSSession
• Get-PSSession
• Invoke-Command
• Receive-PSSession
• Удалить-PSSession