New-PSSession
Crée une connexion persistante à un ordinateur local ou distant.
Syntaxe
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
[-Name <String[]>]
[-UseWindowsPowerShell]
[<CommonParameters>]New-PSSession
[-Name <String[]>]
[-Port <Int32>]
[-HostName] <String[]>
[-UserName <String>]
[-KeyFilePath <String>]
[-Subsystem <String>]
[-ConnectingTimeout <Int32>]
[-SSHTransport]
[-Options <Hashtable>]
[<CommonParameters>]New-PSSession
[-Name <String[]>]
-SSHConnection <Hashtable[]>
[<CommonParameters>]Description
L’applet New-PSSession de commande crée une session PowerShell (PSSession) sur un ordinateur local ou distant. Lorsque vous créez une session PSSession, PowerShell établit une connexion persistante à l’ordinateur distant.
Utilisez une session PSSession pour exécuter plusieurs commandes qui partagent des données, telles qu’une fonction ou la valeur d’une variable. Pour exécuter des commandes dans une session PSSession, utilisez l’applet de Invoke-Command commande. Pour utiliser psSession pour interagir directement avec un ordinateur distant, utilisez l’applet de Enter-PSSession commande. Pour plus d’informations, consultez about_PSSessions.
Vous pouvez exécuter des commandes sur un ordinateur distant sans créer de session PSSession avec les paramètres ComputerName de Enter-PSSession ou Invoke-Command. Lorsque vous utilisez le paramètre ComputerName , PowerShell crée une connexion temporaire utilisée pour la commande, puis fermée.
À compter de PowerShell 6.0, vous pouvez utiliser Secure Shell (SSH) pour établir une connexion et créer une session sur un ordinateur distant, si SSH est disponible sur l’ordinateur local et que l’ordinateur distant est configuré avec un point de terminaison SSH PowerShell. L’avantage d’une session à distance PowerShell basée sur SSH est qu’elle peut fonctionner sur plusieurs plateformes (Windows, Linux, macOS). Pour les sessions basées sur SSH, vous utilisez le paramètre HostName ou SSHConnection défini pour spécifier l’ordinateur distant et les informations de connexion pertinentes. Pour plus d’informations sur la configuration de la communication à distance SSH PowerShell, consultez La communication à distance PowerShell via SSH.
Remarque
Lorsque vous utilisez la communication à distance WSMan à partir d’un client Linux ou macOS avec un point de terminaison HTTPS où le certificat de serveur n’est pas approuvé (par exemple, un certificat auto-signé). Vous devez fournir une option PSSessionOption qui inclut les valeurs SkipCACheck et SkipCNCheck définies pour $true établir correctement la connexion. Effectuez cette opération uniquement si vous êtes dans un environnement où vous pouvez être certain du certificat de serveur et de la connexion réseau au système cible.
Exemples
Exemple 1 : Créer une session sur l’ordinateur local
$s = New-PSSessionCette commande crée une session PSSession sur l’ordinateur local et enregistre la session PSSession dans la $s variable.
Vous pouvez maintenant utiliser cette session PSSession pour exécuter des commandes sur l’ordinateur local.
Exemple 2 : Créer une session sur un ordinateur distant
$Server01 = New-PSSession -ComputerName Server01Cette commande crée une session PSSession sur l’ordinateur Server01 et l’enregistre dans la $Server01 variable.
Lors de la création de plusieurs objets PSSession , affectez-les à des variables avec des noms utiles. Cela vous aidera à gérer les objets PSSession dans les commandes suivantes.
Exemple 3 : Créer des sessions sur plusieurs ordinateurs
$s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03Cette commande crée trois objets PSSession , un sur chacun des ordinateurs spécifiés par le paramètre ComputerName .
La commande utilise l’opérateur d’affectation (=) pour affecter les nouveaux objets PSSession à des variables : $s1, $s2, $s3. Il affecte la session PSSession Server01 à $s1, à Server02 PSSession $s2et à Server03 PSSession à $s3.
Lorsque vous affectez plusieurs objets à une série de variables, PowerShell affecte chaque objet à une variable de la série respectivement. S'il y a plus d'objets que de variables, tous les objets restants sont affectés à la dernière variable. S’il existe plus de variables que d’objets, les variables restantes sont vides ($null).
Exemple 4 : Créer une session avec un port spécifié
New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12Cette commande crée une session PSSession sur l’ordinateur Server01 qui se connecte au port 8081 du serveur et utilise le protocole SSL. La nouvelle session PSSession utilise une autre configuration de session appelée E12.
Avant de définir le port, vous devez configurer l'écouteur WinRM sur l'ordinateur distant afin d'écouter sur le port 8081. Pour plus d’informations, consultez la description du paramètre Port .
Exemple 5 : Créer une session basée sur une session existante
New-PSSession -Session $s -Credential Domain01\User01Cette commande crée une session PSSession avec les mêmes propriétés qu’une session PSSession existante. Vous pouvez utiliser ce format de commande lorsque les ressources d’une session PSSession existante sont épuisées et qu’une nouvelle session PSSession est nécessaire pour décharger une partie de la demande.
La commande utilise le paramètre Session de New-PSSession pour spécifier la session enregistrée dans la $s variable. Il utilise les informations d’identification de l’utilisateur Domain1\Admin01 pour terminer la commande.
Exemple 6 : Créer une session avec une étendue globale dans un autre domaine
$global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01Cet exemple montre comment créer une session PSSession avec une étendue globale sur un ordinateur dans un autre domaine.
Par défaut, les objets PSSession créés sur la ligne de commande sont créés avec l’étendue locale et les objets PSSession créés dans un script ont une étendue de script.
Pour créer une session PSSession avec une étendue globale, créez une session PSSession, puis stockez la session PSSession dans une variable qui est convertie en étendue globale. Dans ce cas, la $s variable est convertie en étendue globale.
La commande utilise le paramètre ComputerName pour spécifier l’ordinateur distant. Étant donné que l’ordinateur se trouve dans un domaine différent du compte d’utilisateur, le nom complet de l’ordinateur est spécifié avec les informations d’identification de l’utilisateur.
Exemple 7 : Créer des sessions pour de nombreux ordinateurs
$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50Cette commande crée une session PSSession sur chacun des 200 ordinateurs répertoriés dans le Servers.txt fichier et stocke la session PSSession résultante dans la $rs variable. Les objets PSSession ont une limite de 50.
Vous pouvez utiliser ce format de commande lorsque les noms des ordinateurs sont stockés dans une base de données, une feuille de calcul, un fichier texte ou tout autre format convertible en texte.
Exemple 8 : Créer une session à l’aide d’un URI
$s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01Cette commande crée une session PSSession sur l’ordinateur Server01 et la stocke dans la $s variable. Il utilise le paramètre URI pour spécifier le protocole de transport, l’ordinateur distant, le port et une autre configuration de session. Il utilise également le paramètre Credential pour spécifier un compte d’utilisateur autorisé à créer une session sur l’ordinateur distant.
Exemple 9 : Exécuter un travail en arrière-plan dans un ensemble de sessions
$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJobCes commandes créent un ensemble d’objets PSSession , puis exécutent un travail en arrière-plan dans chacun des objets PSSession .
La première commande crée une session PSSession sur chacun des ordinateurs répertoriés dans le Servers.txt fichier. Il utilise l’applet New-PSSession de commande pour créer la session PSSession. La valeur du paramètre ComputerName est une commande qui utilise l’applet Get-Content de commande pour obtenir la liste des noms d’ordinateurs du Servers.txt fichier.
La commande utilise le paramètre Credential pour créer les objets PSSession qui ont l’autorisation d’un administrateur de domaine et utilise le paramètre ThrottleLimit pour limiter la commande aux 16 connexions simultanées. La commande enregistre les objets PSSession dans la $s variable.
La deuxième commande utilise le paramètre AsJob de l’applet Invoke-Command de commande pour démarrer un travail en arrière-plan qui exécute une Get-Process PowerShell commande dans chacun des objets PSSession dans $s.
Pour plus d’informations sur les travaux en arrière-plan PowerShell, consultez about_Jobs et about_Remote_Jobs.
Exemple 10 : Créer une session pour un ordinateur à l’aide de son URI
New-PSSession -ConnectionURI https://management.exchangelabs.com/ManagementCette commande crée un objet PSSession qui se connecte à un ordinateur spécifié par un URI au lieu d’un nom d’ordinateur.
Exemple 11 : Créer une option de session
$so = New-PSSessionOption -SkipCACheck
New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01Cet exemple montre comment créer un objet d’option de session et utiliser le paramètre SessionOption .
La première commande utilise l’applet New-PSSessionOption de commande pour créer une option de session. Il enregistre l’objet SessionOption résultant dans la $so variable.
La deuxième commande utilise l'option d'une nouvelle session. La commande utilise l’applet New-PSSession de commande pour créer une session. La valeur du paramètre SessionOption est l’objet SessionOption dans la $so variable.
Exemple 12 : Créer une session à l’aide de SSH
New-PSSession -HostName UserA@LinuxServer01Cet exemple montre comment créer une session PSSession à l’aide de Secure Shell (SSH). Si SSH est configuré sur l’ordinateur distant pour demander des mots de passe, vous obtenez une invite de mot de passe. Sinon, vous devrez utiliser l’authentification utilisateur basée sur une clé SSH.
Exemple 13 : Créer une session à l’aide de SSH et spécifier le port et la clé d’authentification utilisateur
New-PSSession -HostName UserA@LinuxServer01:22 -KeyFilePath c:\<path>\userAKey_rsaCet exemple montre comment créer une session PSSession à l’aide de Secure Shell (SSH). Il utilise le paramètre Port pour spécifier le port à utiliser et le paramètre KeyFilePath pour spécifier une clé RSA utilisée pour identifier et authentifier l’utilisateur sur l’ordinateur distant.
Exemple 14 : Créer plusieurs sessions à l’aide de 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 $sshConnectionsCet exemple montre comment créer plusieurs sessions à l’aide de Secure Shell (SSH) et du jeu de paramètres SSHConnection . Le paramètre SSHConnection prend un tableau de tables de hachage qui contiennent des informations de connexion pour chaque session. Notez que cet exemple nécessite que les ordinateurs distants cibles aient configuré SSH pour prendre en charge l’authentification utilisateur basée sur des clés.
Exemple 15 : Créer une session à l’aide d’options SSH
$options = @{
Port=22
User = 'UserB'
Host = 'LinuxServer5'
}
New-PSSession -KeyFilePath '/Users/UserB/id_rsa' -Options $optionsCet exemple montre comment créer une session BASÉE sur SSH sur une machine Linux distante à l’aide d’options SSH. Le paramètre Options prend une table de hachage de valeurs qui sont passées en tant qu’options à la commande sous-jacente ssh , la connexion établie au système distant.
Paramètres
-AllowRedirection
Indique que cette applet de commande autorise la redirection de cette connexion vers un AUTRE URI (Uniform Resource Identifier).
Lorsque vous utilisez le paramètre ConnectionURI , la destination distante peut retourner une instruction pour rediriger vers un AUTRE URI. Par défaut, PowerShell ne redirige pas les connexions, mais vous pouvez utiliser ce paramètre pour l’activer pour rediriger la connexion.
Vous pouvez également limiter le nombre de fois où la connexion est redirigée en modifiant la valeur de l’option de session MaximumConnectionRedirectionCount . Utilisez le paramètre MaximumRedirection de l’applet New-PSSessionOption de commande ou définissez la propriété MaximumConnectionRedirectionCount de la variable de préférence $PSSessionOption. La valeur par défaut est 5.
| Type: | SwitchParameter |
| Position: | Named |
| Valeur par défaut: | False |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-ApplicationName
Spécifie le segment de nom d'application de l'URI de connexion. Utilisez ce paramètre pour spécifier le nom de l’application lorsque vous n’utilisez pas le paramètre ConnectionURI dans la commande.
La valeur par défaut est la valeur de la $PSSessionApplicationName variable de préférence sur l’ordinateur local. Si cette variable de préférence n’est pas définie, la valeur par défaut est WSMAN. Cette valeur convient pour la plupart des utilisations. Pour plus d’informations, consultez about_Preference_Variables.
Le service WinRM utilise le nom de l'application pour sélectionner un port d'écoute et traiter la demande de connexion. La valeur de ce paramètre doit correspondre à la valeur de la propriété URLPrefix d’un écouteur sur l’ordinateur distant.
| Type: | String |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-Authentication
Spécifie le mécanisme permettant d'authentifier les informations d'identification de l'utilisateur. Les valeurs valides pour ce paramètre sont :
DefaultBasicCredsspDigestKerberosNegotiateNegotiateWithImplicitCredential
La valeur par défaut est Default.
Pour plus d’informations sur les valeurs de ce paramètre, consultez AuthenticationMechanism, énumération.
Attention
L’authentification CredSSP (Credential Security Support Provider), dans laquelle les informations d’identification de l’utilisateur sont transmises à un ordinateur distant à authentifier, est conçue pour les commandes qui nécessitent une authentification sur plusieurs ressources, telles que l’accès à un partage réseau distant. Ce mécanisme augmente le risque de sécurité lié à l'opération distante. Si l'ordinateur distant n'est pas fiable, les informations d'identification qui lui sont passées peuvent être utilisées pour contrôler la session réseau.
| Type: | AuthenticationMechanism |
| Valeurs acceptées: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-CertificateThumbprint
Spécifie le certificat de clé publique numérique (X509) d'un compte d'utilisateur qui a l'autorisation d'exécuter cette action. Entrez l’empreinte numérique du certificat.
Les certificats sont utilisés dans l'authentification par certificat client. Ils peuvent être mappés uniquement aux comptes d'utilisateur locaux ; ils ne fonctionnent pas avec les comptes de domaine.
Pour obtenir un certificat, utilisez le ou Get-ChildItem la Get-Item commande dans le lecteur PowerShellCert:.
| Type: | String |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-ComputerName
Spécifie un tableau de noms d’ordinateurs. Cette applet de commande crée une connexion persistante (PSSession) à l’ordinateur spécifié. Si vous entrez plusieurs noms d’ordinateurs, New-PSSession crée plusieurs objets PSSession , un pour chaque ordinateur. La valeur par défaut est l'ordinateur local.
Tapez le nom NetBIOS, l'adresse IP ou le nom de domaine complet d'un ou de plusieurs ordinateurs distants. Pour spécifier l’ordinateur local, tapez le nom de l’ordinateur, localhostou un point (.). Lorsque l'ordinateur distant se trouve dans un domaine différent de celui de l'utilisateur, le nom de domaine complet est obligatoire.
Vous pouvez également diriger un nom d’ordinateur, entre guillemets, vers New-PSSession.
Pour utiliser une adresse IP dans la valeur du paramètre ComputerName , la commande doit inclure le paramètre Credential . En outre, l'ordinateur doit être configuré pour le transport HTTPS ou l'adresse IP de l'ordinateur distant doit être incluse dans la liste TrustedHosts pour WinRM de l'ordinateur local. Pour obtenir des instructions sur l’ajout d’un nom d’ordinateur à la liste TrustedHosts, consultez « How to Add a Computer to the Trusted Host List » dans about_Remote_Troubleshooting.
Pour inclure l’ordinateur local dans la valeur du paramètre ComputerName, démarrez Windows PowerShell à l’aide de l’option Exécuter en tant qu’administrateur.
| Type: | String[] |
| Alias: | Cn |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-ConfigurationName
Spécifie la configuration de session utilisée pour la nouvelle session PSSession.
Entrez un nom de configuration ou l'URI de ressource complet d'une configuration de session. Si vous spécifiez uniquement le nom de configuration, l’URI de schéma suivant est prédéfini : http://schemas.microsoft.com/PowerShell.
La configuration d'une session se trouve sur l'ordinateur distant. Si la configuration de session spécifiée n'existe pas sur l'ordinateur distant, la commande échoue.
La valeur par défaut est la valeur de la $PSSessionConfigurationName variable de préférence sur l’ordinateur local. Si cette variable de préférence n’est pas définie, la valeur par défaut est Microsoft.PowerShell. Pour plus d’informations, consultez about_Preference_Variables.
| Type: | String |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-ConnectingTimeout
Spécifie la durée en millisecondes autorisée pour la fin de la connexion SSH initiale. Si la connexion ne se termine pas dans le délai spécifié, une erreur est retournée.
Ce paramètre a été introduit dans PowerShell 7.2
| Type: | Int32 |
| Position: | Named |
| Valeur par défaut: | unlimited |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-ConnectionUri
Spécifie un URI qui définit le point de terminaison de connexion de la session. L’URI doit être complet. Le format de cette chaîne est le suivant :
<Transport>://<ComputerName>:<Port>/<ApplicationName>
La valeur par défaut est la suivante :
http://localhost:5985/WSMAN
Si vous ne spécifiez pas connectionURI, vous pouvez utiliser les paramètres UseSSL, ComputerName, Port et ApplicationName pour spécifier les valeurs ConnectionURI.
Les valeurs valides du segment Transport de l'URI sont HTTP et HTTPS. Si vous spécifiez un URI de connexion avec un segment de transport, mais que vous ne spécifiez pas de port, la session est créée avec des ports standards : 80 pour HTTP et 443 pour HTTPS. Pour utiliser les ports par défaut pour la communication à distance PowerShell, spécifiez le port 5985 http ou 5986 https.
Si l’ordinateur de destination redirige la connexion vers un autre URI, PowerShell empêche la redirection, sauf si vous utilisez le paramètre AllowRedirection dans la commande.
| Type: | Uri[] |
| Alias: | URI, CU |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-ContainerId
Spécifie un tableau d’ID de conteneurs. Cette applet de commande démarre une session interactive avec chacun des conteneurs spécifiés. Utilisez la docker ps commande pour obtenir la liste des ID de conteneur. Pour plus d’informations, consultez l’aide de la commande docker ps .
| Type: | String[] |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-Credential
Spécifie un compte d’utilisateur autorisé à effectuer cette action. La valeur par défaut est l’utilisateur actuel.
Tapez un nom d’utilisateur, tel que User01 ou Domain01\User01, ou entrez un objet PSCredential généré par l’applet Get-Credential de commande. Si vous tapez un nom d’utilisateur, vous êtes invité à entrer le mot de passe.
Les informations d’identification sont stockées dans un objet PSCredential et le mot de passe est stocké en tant que SecureString.
Remarque
Pour plus d’informations sur la protection des données SecureString , consultez Comment secure is SecureString ?.
| Type: | PSCredential |
| Position: | Named |
| Valeur par défaut: | Current user |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-EnableNetworkAccess
Indique que cette applet de commande ajoute un jeton de sécurité interactif aux sessions de bouclage. Le jeton interactif vous permet d'exécuter des commandes dans la session de bouclage qui obtiennent des données à partir d'autres ordinateurs. Par exemple, vous pouvez exécuter une commande dans la session qui copie les fichiers XML d'un ordinateur distant vers l'ordinateur local.
Une session de bouclage est une session PSSession qui provient et se termine sur le même ordinateur. Pour créer une session de bouclage, omettez le paramètre ComputerName ou définissez sa valeur sur point (.), localhostou le nom de l’ordinateur local.
Par défaut, cette applet de commande crée des sessions de bouclage à l’aide d’un jeton réseau, ce qui peut ne pas fournir l’autorisation suffisante pour s’authentifier auprès des ordinateurs distants.
Le paramètre EnableNetworkAccess est efficace uniquement dans les sessions de bouclage. Si vous utilisez EnableNetworkAccess lorsque vous créez une session sur un ordinateur distant, la commande réussit, mais le paramètre est ignoré.
Vous pouvez également activer l’accès à distance dans une session de bouclage à l’aide de la CredSSP valeur du paramètre d’authentification , qui délègue les informations d’identification de session à d’autres ordinateurs.
Pour protéger l’ordinateur contre les accès malveillants, les sessions de bouclage déconnectées qui ont des jetons interactifs, qui sont ceux créés à l’aide du paramètre EnableNetworkAccess , peuvent être reconnectées uniquement à partir de l’ordinateur sur lequel la session a été créée. Les sessions déconnectées qui utilisent l'authentification CredSSP peuvent être reconnectées à partir d'autres ordinateurs. Pour plus d’informations, consultez Disconnect-PSSession.
Ce paramètre a été introduit dans PowerShell 3.0.
| Type: | SwitchParameter |
| Position: | Named |
| Valeur par défaut: | False |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-HostName
Spécifie un tableau de noms d’ordinateurs pour une connexion SSH (Secure Shell). Cela est similaire au paramètre ComputerName , sauf que la connexion à l’ordinateur distant est établie à l’aide de SSH plutôt que de Windows WinRM.
Ce paramètre a été introduit dans PowerShell 6.0.
| Type: | String[] |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-KeyFilePath
Spécifie un chemin d’accès de fichier de clé utilisé par Secure Shell (SSH) pour authentifier un utilisateur sur un ordinateur distant.
SSH permet à l’utilisateur d’effectuer l’authentification via des clés privées/publiques comme alternative à l’authentification par mot de passe de base. Si l’ordinateur distant est configuré pour l’authentification par clé, ce paramètre peut être utilisé pour fournir la clé qui identifie l’utilisateur.
Ce paramètre a été introduit dans PowerShell 6.0.
| Type: | String |
| Alias: | IdentityFilePath |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-Name
Spécifie un nom convivial pour la session PSSession.
Vous pouvez utiliser le nom pour faire référence à la session PSSession lorsque vous utilisez d’autres applets de commande, telles que Get-PSSession et Enter-PSSession. Le nom n'a pas obligatoirement à être unique sur l'ordinateur ou dans la session active.
| Type: | String[] |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-Options
Spécifie une table de hachage des options SSH utilisées lors de la connexion à une session SSH distante. Les options possibles sont toutes les valeurs prises en charge par la version unix de la commande ssh .
Toutes les valeurs transmises explicitement par les paramètres sont prioritaires sur les valeurs passées dans la table de hachage Options . Par exemple, l’utilisation du paramètre Port remplace toute Port paire clé-valeur passée dans la table de hachage Options .
| Type: | Hashtable |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-Port
Spécifie le port réseau sur l’ordinateur distant utilisé pour cette connexion. Pour établir une connexion à un ordinateur distant, l’ordinateur distant doit être à l’écoute sur le port utilisé par la connexion. Les ports par défaut sont 5985, qui est le port WinRM pour HTTP, et 5986, qui est le port WinRM pour HTTPS.
Avant d’utiliser un autre port, vous devez configurer l’écouteur WinRM sur l’ordinateur distant pour écouter sur ce port. Utilisez les commandes suivantes pour configurer l'écouteur :
winrm delete winrm/config/listener?Address=*+Transport=HTTPwinrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}
N’utilisez pas le paramètre Port , sauf si vous devez. Le paramètre de port de la commande s'applique à tous les ordinateurs ou sessions sur lesquels la commande s'exécute. Un autre paramètre de port peut empêcher la commande de s'exécuter sur tous les ordinateurs.
| Type: | Int32 |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-RunAsAdministrator
Indique que la session PSSession s’exécute en tant qu’administrateur.
| Type: | SwitchParameter |
| Position: | Named |
| Valeur par défaut: | False |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-Session
Spécifie un tableau d’objets PSSession que cette applet de commande utilise comme modèle pour la nouvelle session PSSession. Ce paramètre crée des objets PSSession qui ont les mêmes propriétés que les objets PSSession spécifiés.
Entrez une variable qui contient les objets PSSession ou une commande qui crée ou obtient les objets PSSession, tels qu’une ou Get-PSSession une New-PSSession commande.
Les objets PSSession résultants ont le même nom d’ordinateur, le nom de l’application, l’URI de connexion, le port, le nom de configuration, la limite de limitation et la valeur SSL (Secure Sockets Layer) que les originaux, mais ils ont un autre nom d’affichage, ID et ID d’instance (GUID).
| Type: | PSSession[] |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-SessionOption
Spécifie les options avancées de la session. Entrez un objet SessionOption , tel qu’un objet que vous créez à l’aide de l’applet New-PSSessionOption de commande, ou une table de hachage dans laquelle les clés sont des noms d’options de session et les valeurs sont des valeurs d’option de session.
Les valeurs par défaut des options sont déterminées par la valeur de la $PSSessionOption variable de préférence, si elle est définie. Sinon, les valeurs par défaut sont établies par les options définies dans la configuration de session.
Les valeurs d’option de session sont prioritaires sur les valeurs par défaut pour les sessions définies dans la $PSSessionOption variable de préférence et dans la configuration de session. Elles ne sont cependant pas prioritaires sur les valeurs maximales, les quotas ou les limites définis dans la configuration de session.
Pour obtenir une description des options de session qui inclut les valeurs par défaut, consultez New-PSSessionOption. Pour plus d’informations sur la $PSSessionOption variable de préférence, consultez about_Preference_Variables. Pour plus d'informations sur les configurations de session, consultez about_Session_Configurations.
| Type: | PSSessionOption |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-SSHConnection
Ce paramètre prend un tableau de tables de hachage où chaque table de hachage contient un ou plusieurs paramètres de connexion nécessaires pour établir une connexion Secure Shell (SSH) (HostName, Port, UserName, KeyFilePath).
Les paramètres de connexion de table de hachage sont identiques à ceux définis pour le jeu de paramètres SSHHost .
Le paramètre SSHConnection est utile pour créer plusieurs sessions où chaque session nécessite des informations de connexion différentes.
Ce paramètre a été introduit dans PowerShell 6.0.
| Type: | Hashtable[] |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-SSHTransport
Indique que la connexion à distance est établie à l’aide de Secure Shell (SSH).
Par défaut, PowerShell utilise Windows WinRM pour se connecter à un ordinateur distant. Ce commutateur force PowerShell à utiliser l’ensemble de paramètres HostName pour établir une connexion distante basée sur SSH.
Ce paramètre a été introduit dans PowerShell 6.0.
| Type: | SwitchParameter |
| Valeurs acceptées: | true |
| Position: | Named |
| Valeur par défaut: | False |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-Subsystem
Spécifie le sous-système SSH utilisé pour la nouvelle session PSSession.
Cela spécifie le sous-système à utiliser sur la cible comme défini dans sshd_config. Le sous-système démarre une version spécifique de PowerShell avec des paramètres prédéfinis. Si le sous-système spécifié n’existe pas sur l’ordinateur distant, la commande échoue.
Si ce paramètre n’est pas utilisé, la valeur par défaut est le powershell sous-système.
| Type: | String |
| Position: | Named |
| Valeur par défaut: | powershell |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-ThrottleLimit
Spécifie le nombre maximal de connexions simultanées qui peuvent être établies pour exécuter cette commande.
Si vous omettez ce paramètre ou entrez une valeur de 0 (zéro), la valeur par défaut, 32est utilisée.
La limite d'accélération s'applique uniquement à la commande actuelle, et non à la session ou à l'ordinateur.
| Type: | Int32 |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-UserName
Spécifie le nom d’utilisateur du compte utilisé pour créer une session sur l’ordinateur distant. La méthode d’authentification utilisateur dépend de la configuration de Secure Shell (SSH) sur l’ordinateur distant.
Si SSH est configuré pour l’authentification par mot de passe de base, vous êtes invité à entrer le mot de passe de l’utilisateur.
Si SSH est configuré pour l’authentification utilisateur basée sur des clés, un chemin d’accès de fichier de clé peut être fourni via le paramètre KeyFilePath et vous ne serez pas invité à entrer un mot de passe. Notez que si le fichier de clé utilisateur client se trouve à un emplacement connu SSH, le paramètre KeyFilePath n’est pas nécessaire pour l’authentification basée sur des clés, et l’authentification utilisateur se produit automatiquement en fonction du nom d’utilisateur. Pour plus d’informations, consultez la documentation SSH sur l’authentification utilisateur basée sur des clés.
Ce paramètre n’est pas obligatoire. Si aucun paramètre UserName n’est spécifié, le nom d’utilisateur actuel est utilisé pour la connexion.
Ce paramètre a été introduit dans PowerShell 6.0.
| Type: | String |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-UseSSL
Indique que cette applet de commande utilise le protocole SSL pour établir une connexion à l’ordinateur distant. Par défaut, SSL n'est pas utilisé.
WS-Management chiffre tout le contenu PowerShell transmis sur le réseau. Le paramètre UseSSL offre une protection supplémentaire qui envoie les données sur une connexion HTTPS au lieu d’une connexion HTTP.
Si vous utilisez ce paramètre, mais que SSL n’est pas disponible sur le port utilisé pour la commande, la commande échoue.
| Type: | SwitchParameter |
| Position: | Named |
| Valeur par défaut: | False |
| Obligatoire: | False |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-UseWindowsPowerShell
Crée une connexion à distance à un nouvel espace d’exécution Windows PowerShell sur le système local.
| Type: | SwitchParameter |
| Position: | Named |
| Valeur par défaut: | False |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | False |
| Accepter les caractères génériques: | False |
-VMId
Spécifie un tableau d’ID de machine virtuelle. Cette applet de commande démarre une session interactive PowerShell Direct avec chacune des machines virtuelles spécifiées. Pour plus d’informations, consultez l’automatisation et la gestion des machines virtuelles à l’aide de PowerShell.
Permet Get-VM de voir les machines virtuelles disponibles sur votre hôte Hyper-V.
| Type: | Guid[] |
| Alias: | VMGuid |
| Position: | 0 |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
-VMName
Spécifie un tableau de noms d'ordinateurs virtuels. Cette applet de commande démarre une session interactive PowerShell Direct avec chacune des machines virtuelles spécifiées. Pour plus d’informations, consultez l’automatisation et la gestion des machines virtuelles à l’aide de PowerShell.
Permet Get-VM de voir les machines virtuelles disponibles sur votre hôte Hyper-V.
| Type: | String[] |
| Position: | Named |
| Valeur par défaut: | None |
| Obligatoire: | True |
| Accepter l'entrée de pipeline: | True |
| Accepter les caractères génériques: | False |
Entrées
Vous pouvez diriger une chaîne vers cette applet de commande.
System.URI
Vous pouvez diriger un URI vers cette applet de commande.
Vous pouvez diriger un objet de session vers cette applet de commande.
Sorties
Notes
PowerShell inclut les alias suivants pour New-PSSession:
Toutes les plateformes :
nsn
Cette applet de commande utilise l’infrastructure de communication à distance PowerShell. Pour utiliser cette applet de commande, l’ordinateur local et tous les ordinateurs distants doivent être configurés pour la communication à distance PowerShell. Pour plus d’informations, consultez about_Remote_Requirements.
Pour créer une session PSSession sur l’ordinateur local, démarrez PowerShell avec l’option Exécuter en tant qu’administrateur .
Une fois la session PSSession terminée, utilisez l’applet
Remove-PSSessionde commande pour supprimer la session PSSession et libérer ses ressources.Les ensembles de paramètres HostName et SSHConnection ont été inclus à partir de PowerShell 6.0. Ils ont été ajoutés pour fournir la communication à distance PowerShell basée sur Secure Shell (SSH). SSH et PowerShell sont pris en charge sur plusieurs plateformes (Windows, Linux, macOS) et la communication à distance PowerShell fonctionnent sur ces plateformes où PowerShell et SSH sont installés et configurés. Cela est distinct de la communication à distance Windows précédente basée sur WinRM et la plupart des fonctionnalités et limitations spécifiques de WinRM ne s’appliquent pas. Par exemple, les quotas winRM, les options de session, la configuration de point de terminaison personnalisée et les fonctionnalités de déconnexion/reconnexion ne sont pas prises en charge. Pour plus d’informations sur la configuration de la communication à distance SSH PowerShell, consultez La communication à distance PowerShell via SSH.
L’exécutable ssh obtient les données de configuration à partir des sources suivantes dans l’ordre suivant :
- options de ligne de commande
- fichier de configuration de l’utilisateur (~/.ssh/config)
- fichier de configuration à l’échelle du système (/etc/ssh/ssh_config)
Les paramètres d’applet de commande suivants sont mappés dans ssh les paramètres et les options :
| Paramètre d’applet de commande | paramètre ssh | option ssh -o équivalente |
|---|---|---|
-KeyFilePath |
-i <KeyFilePath> |
-o IdentityFile=<KeyFilePath> |
-UserName |
-l <UserName> |
-o User=<UserName> |
-Port |
-p <Port> |
-o Port=<Port> |
-ComputerName -Subsystem |
-s <ComputerName> <Subsystem> |
-o Host=<ComputerName> |
Toutes les valeurs transmises explicitement par les paramètres sont prioritaires sur les valeurs passées dans la table de hachage Options . Pour plus d’informations sur les ssh_config fichiers, consultez ssh_config(5).
