Enter-PSSession
Démarre une session interactive avec un ordinateur distant.
Syntaxe
Enter-PSSession [-ComputerName] <string> [-ApplicationName <string>] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Port <int>] [-SessionOption <PSSessionOption>] [-UseSSL] [<CommonParameters>]
Enter-PSSession [[-Id] <int>] [<CommonParameters>]
Enter-PSSession [-InstanceId <Guid>] [<CommonParameters>]
Enter-PSSession [-Name <string>] [<CommonParameters>]
Enter-PSSession [[-Session] <PSSession>] [<CommonParameters>]
Enter-PSSession [[-ConnectionURI] <Uri>] [-AllowRedirection] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-SessionOption <PSSessionOption>] [<CommonParameters>]
Description
L'applet de commande Enter-PSSession démarre une session interactive avec un ordinateur distant unique. Pendant la session, les commandes que vous tapez s'exécutent sur l'ordinateur distant comme si vous les y entriez directement. Une seule session interactive peut être active à la fois.
En général, vous utilisez le paramètre ComputerName pour spécifier le nom de l'ordinateur distant. Toutefois, vous pouvez également utiliser une session que vous créez en utilisant New-PSSession pour la session interactive.
Pour mettre fin à la session interactive et vous déconnecter de l'ordinateur distant, utilisez l'applet de commande Exit-PSSession ou tapez « exit ».
Paramètres
-AllowRedirection
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 URI différent. Par défaut, Windows PowerShell ne redirige pas les connexions, mais vous pouvez utiliser ce paramètre pour lui permettre de le faire.
Autorise la redirection de cette connexion vers un autre URI.
Lorsque vous utilisez le paramètre ConnectionURI, la destination distante peut retourner une instruction pour rediriger vers un URI différent. Par défaut, Windows PowerShell ne redirige pas les connexions, mais vous pouvez utiliser le paramètre AllowRedirection pour lui permettre de rediriger la connexion.
Vous pouvez également limiter le nombre de redirections de la connexion en définissant la propriété MaximumConnectionRedirectionCount de la variable de préférence $PSSessionOption ou la propriété MaximumConnectionRedirectionCount de la valeur du paramètre SessionOption. La valeur par défaut est 5. Pour plus d'informations, consultez la description du paramètre SessionOption et New-PSSessionOption.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
False |
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-ApplicationName <string>
Spécifie le segment du nom d'application dans l'URI de connexion. Utilisez ce paramètre pour spécifier le nom d'application lorsque vous n'employez pas le paramètre ConnectionURI dans la commande.
La valeur par défaut est la valeur de la variable de préférence $PSSessionApplicationName 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 d'application afin de sélectionner un écouteur pour le traitement de la demande de connexion. La valeur de ce paramètre doit correspondre à celle de la propriété URLPrefix d'un écouteur sur l'ordinateur distant.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
WSMAN |
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Authentication <AuthenticationMechanism>
Spécifie le mécanisme permettant d'authentifier les informations d'identification de l'utilisateur. Les valeurs valides sont « Default », « Basic », « Credssp », « Digest », « Kerberos », « Negotiate » et « NegotiateWithImplicitCredential ». La valeur par défaut est « Default ».
L'authentification CredSSP n'est disponible que dans Windows Vista, Windows Server 2008 et les versions ultérieures de Windows.
Pour plus d'informations sur les valeurs de ce paramètre, consultez la description de l'énumération System.Management.Automation.Runspaces.AuthenticationMechanism dans la bibliothèque MSDN (Microsoft Developer Network) à l'adresse https://go.microsoft.com/fwlink/?LinkId=144382.
Attention : l'authentification CredSSP (Credential Security Service Provider), au cours de laquelle les informations d'identification de l'utilisateur sont passées à un ordinateur distant pour être authentifiées, est conçue pour les commandes qui requièrent 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.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-CertificateThumbprint <string>
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 une authentification basée sur les certificats clients. Ils peuvent être mappés uniquement à des comptes d'utilisateur local ; ils ne fonctionnent pas avec des comptes de domaine.
Pour obtenir une empreinte numérique de certificat, utilisez la commande Get-Item ou Get-ChildItem sur le lecteur Cert: de Windows PowerShell.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-ComputerName <string>
Démarre une session interactive avec l'ordinateur distant spécifié. Entrez un seul nom d'ordinateur. La valeur par défaut est l'ordinateur local.
Tapez le nom NetBIOS, une adresse IP ou un nom de domaine complet d'un ou de plusieurs ordinateurs distants. Vous pouvez également diriger un nom d'ordinateur vers Enter-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 WinRM de l'ordinateur local. Pour obtenir des instructions sur l'ajout d'un nom d'ordinateur à la liste TrustedHosts, consultez « Comment ajouter un ordinateur à la liste des hôtes approuvés » dans about_Remote_Troubleshooting.
Remarque : dans Windows Vista et les versions ultérieures de Windows, pour inclure l'ordinateur local dans la valeur du paramètre ComputerName, vous devez démarrer Windows PowerShell avec l'option Exécuter en tant qu'administrateur.
Obligatoire ? |
true |
Position ? |
1 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByValue, ByPropertyName) |
Accepter les caractères génériques ? |
false |
-ConfigurationName <string>
Spécifie la configuration de session utilisée pour la session interactive.
Entrez un nom de configuration ou l'URI de ressource complet d'une configuration de session. Si vous spécifiez uniquement le nom de la configuration, l'URI de schéma suivant est ajouté en tant que préfixe : https://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 variable de préférence $PSSessionConfigurationName 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.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-ConnectionURI <Uri>
Spécifie un URI (Uniform Resource Identifier) qui définit le point de terminaison de connexion de la session interactive. 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 :
https://localhost:80/WSMAN
Les valeurs valides pour le segment Transport de l'URI sont HTTP et HTTPS. Si vous ne spécifiez pas de valeur ConnectionURI, vous pouvez utiliser les paramètres UseSSL, ComputerName, Port et ApplicationName pour indiquer les valeurs d'URI.
Si l'ordinateur de destination redirige la connexion vers un URI différent, Windows PowerShell empêche la redirection à moins que vous n'utilisiez le paramètre AllowRedirection dans la commande.
Obligatoire ? |
false |
Position ? |
2 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Credential <PSCredential>
Spécifie un compte d'utilisateur qui a l'autorisation d'exécuter cette action. La valeur par défaut est l'utilisateur actuel.
Tapez un nom d'utilisateur, comme « Utilisateur01 », « Domaine01\Utilisateur01 » ou « Utilisateur@Domaine.com », ou entrez un objet PSCredential, tel que celui retourné par l'applet de commande Get-Credential.
Lorsque vous tapez un nom d'utilisateur, vous êtes invité à entrer un mot de passe.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
Current user |
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Id <int>
Spécifie l'ID d'une session existante. Enter-PSSession utilise la session spécifiée pour la session interactive.
Pour rechercher l'ID d'une session, utilisez l'applet de commande Get-PSSession.
Obligatoire ? |
false |
Position ? |
1 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-InstanceId <Guid>
Spécifie l'ID d'instance d'une session existante. Enter-PSSession utilise la session spécifiée pour la session interactive.
L'ID d'instance est un GUID. Pour rechercher l'ID d'instance d'une session, utilisez l'applet de commande Get-PSSession. Vous pouvez également utiliser les paramètres Session, Name ou ID pour spécifier une session existante. Vous pouvez aussi utiliser le paramètre ComputerName pour démarrer une session temporaire.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Name <string>
Spécifie le nom convivial d'une session existante. Enter-PSSession utilise la session spécifiée pour la session interactive.
Si le nom que vous spécifiez correspond à plusieurs sessions, la commande échoue. Vous pouvez également utiliser les paramètres Session, InstanceID ou ID pour spécifier une session existante. Vous pouvez aussi utiliser le paramètre ComputerName pour démarrer une session temporaire.
Pour établir un nom convivial pour une session, utilisez le paramètre Name de l'applet de commande New-PSSession.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByPropertyName) |
Accepter les caractères génériques ? |
false |
-Port <int>
Spécifie le port réseau sur l'ordinateur distant utilisé pour cette commande. La valeur par défaut est le port 80 (le port HTTP).
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 :
1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="<numéro-port>"}
N'utilisez pas le paramètre Port à moins d'y être obligé. Le paramètre de port de la commande s'applique à l'ensemble des ordinateurs ou sessions où la commande s'exécute. Le paramètre d'un autre port peut empêcher l'exécution de la commande sur tous les ordinateurs.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-Session <PSSession>
Spécifie une session Windows PowerShell (PSSession) à utiliser pour la session interactive. Ce paramètre accepte un objet session. Vous pouvez également utiliser les paramètres Name, InstanceID ou ID pour spécifier une session PSSession.
Entrez une variable qui contient un objet session ou une commande qui crée ou obtient un objet session, comme une commande New-PSSession ou Get-PSSession. Vous pouvez également diriger un objet session vers Enter-PSSession. Vous ne pouvez envoyer qu'une seule session PSSession avec ce paramètre. Si vous entrez une variable qui contient plusieurs sessions PSSession, la commande échoue.
Lorsque vous utilisez Exit-PSSession ou le mot clé EXIT, la session interactive prend fin, mais la session PSSession que vous avez créée reste ouverte et disponible.
Obligatoire ? |
false |
Position ? |
1 |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
true (ByValue, ByPropertyName) |
Accepter les caractères génériques ? |
true |
-SessionOption <PSSessionOption>
Définit des options avancées pour la session. Entrez un objet SessionOption que vous créez à l'aide de l'applet de commande New-PSSessionOption.
Les valeurs par défaut des options sont déterminées par la valeur de la variable de préférence $PSSessionOption, si elle est définie. Sinon, la session utilise les valeurs par défaut du système.
Pour obtenir une description des options de session, notamment des valeurs par défaut, consultez New-PSSessionOption. Pour plus d'informations sur la variable de préférence $PSSessionOption, consultez about_Preference_Variables.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
-UseSSL
Utilise le protocole SSL (Secure Sockets Layer) pour établir une connexion avec l'ordinateur distant. Par défaut, SSL n'est pas utilisé.
La Gestion des services Web chiffre tout le contenu Windows PowerShell transmis sur le réseau. UseSSL est une protection supplémentaire qui envoie les données via une connexion HTTPS plutôt que HTTP.
Si vous utilisez ce paramètre, mais que SSL n'est pas disponible sur le port utilisé pour la commande, la commande échoue.
Obligatoire ? |
false |
Position ? |
named |
Valeur par défaut |
|
Accepter l'entrée de pipeline ? |
false |
Accepter les caractères génériques ? |
false |
<CommonParameters>
Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.
Entrées et sorties
Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.
Entrées |
System.String ou System.Management.Automation.Runspaces.PSSession Vous pouvez diriger un nom d'ordinateur (une chaîne) ou un objet session vers Enter-PSSession. |
Sorties |
Aucun L'applet de commande ne retourne aucune sortie. |
Remarques
-- Pour vous connecter à un ordinateur distant, vous devez être membre du groupe Administrateurs sur l'ordinateur distant.
-- Dans Windows Vista et les versions ultérieures de Windows, pour démarrer une session interactive sur l'ordinateur local, vous devez ouvrir Windows PowerShell avec l'option Exécuter en tant qu'administrateur.
-- Lorsque vous utilisez Enter-PSSession, votre profil utilisateur sur l'ordinateur distant est utilisé pour la session interactive. Les commandes du profil de l'utilisateur distant, notamment celles permettant d'ajouter des composants logiciels enfichables Windows PowerShell et de modifier l'invite de commandes, s'exécutent avant que l'invite distante ne s'affiche.
-- Enter-PSSession utilise le paramètre de culture d'interface utilisateur défini sur l'ordinateur local pour la session interactive. Pour rechercher la culture d'interface utilisateur locale, utilisez la variable automatique $UICulture.
-- Enter-PSSession requiert les applets de commande Get-Command, Out-Default et Exit-PSSession. Si ces applets de commande ne sont pas incluses dans la configuration de session sur l'ordinateur distant, la commande Enter-PSSession échoue.
-- Contrairement à Invoke-Command, qui analyse et interprète les commandes avant de les envoyer à l'ordinateur distant, Enter-PSSession envoie directement les commandes à l'ordinateur distant sans effectuer d'interprétation.
Exemple 1
C:\PS>Enter-PSSession
LocalHost\PS>
Description
-----------
Cette commande démarre une session interactive sur l'ordinateur local. L'invite de commandes change pour indiquer que vous exécutez à présent des commandes dans une session différente.
Les commandes que vous entrez s'exécutent dans la nouvelle session et les résultats sont renvoyés à la session par défaut sous forme de texte.
Exemple 2
C:\PS>enter-pssession -computer Server01
Server01\PS> get-process powershell > C:\ps-test\process.txt
Server01\PS> exit-pssession
C:\PS>
C:\PS> dir C:\ps-test\process.txt
Get-ChildItem : Cannot find path 'C:\ps-test\process.txt' because it does not exist.
At line:1 char:4
+ dir <<<< c:\ps-test\process.txt
Description
-----------
Cette commande montre comment utiliser un ordinateur distant dans une session interactive.
La première commande utilise l'applet de commande Enter-PSSession pour démarrer une session interactive avec Server01, un ordinateur distant. Lorsque la session démarre, l'invite de commandes change pour inclure le nom de l'ordinateur.
La deuxième commande obtient le processus PowerShell et redirige la sortie vers le fichier Process.txt. Elle est envoyée à l'ordinateur distant et le fichier est enregistré sur ce dernier.
La troisième commande utilise le mot clé Exit pour mettre fin à la session interactive et fermer la connexion.
La quatrième commande confirme que le fichier Process.txt se trouve bien sur l'ordinateur distant. Une commande Get-ChildItem (« dir ») entrée sur l'ordinateur local ne peut pas trouver le fichier.
Exemple 3
C:\PS>$s = new-pssession -computername Server01
C:\PS> Enter-PSSession -session $s
Server01\PS>
Description
-----------
Ces commandes utilisent le paramètre Session de Enter-PSSession pour exécuter la session interactive dans une session Windows PowerShell (PSSession) existante.
Exemple 4
C:\PS>Enter-PSSession -computername Server01 -port 90 -credential domain01\user01
Server01\PS>
Description
-----------
Cette commande démarre une session interactive avec l'ordinateur Server01. Elle utilise le paramètre Port pour spécifier le port et le paramètre Credential pour spécifier le compte d'un utilisateur qui est autorisé à se connecter à l'ordinateur distant.
Exemple 5
C:\PS>Enter-PSSession -computername Server01
Server01:\PS> Exit-PSSession
C:\PS>
Description
-----------
Cet exemple montre comment démarrer et arrêter une session interactive. La première commande utilise l'applet de commande Enter-PSSession pour démarrer une session interactive avec l'ordinateur Server01.
La deuxième commande utilise l'applet de commande Exit-PSSession pour mettre fin à la session. Vous pouvez également utiliser le mot clé Exit pour mettre fin à la session interactive. Exit-PSSession et Exit ont le même effet.
Voir aussi
Concepts
about_PSSessions
about_Remote
New-PSSession
Get-PSSession
Exit-PSSession
Remove-PSSession
Invoke-Command