Enter-PSSession
Inicia una sesión interactiva con un equipo remoto.
Syntax
Enter-PSSession
[-ComputerName] <String>
[-EnableNetworkAccess]
[-Credential <PSCredential>]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-ApplicationName <String>]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]Enter-PSSession
[[-Session] <PSSession>]
[<CommonParameters>]Enter-PSSession
[[-ConnectionUri] <Uri>]
[-EnableNetworkAccess]
[-Credential <PSCredential>]
[-ConfigurationName <String>]
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]Enter-PSSession
[-InstanceId <Guid>]
[<CommonParameters>]Enter-PSSession
[[-Id] <Int32>]
[<CommonParameters>]Enter-PSSession
[-Name <String>]
[<CommonParameters>]Enter-PSSession
[-VMGuid] <Guid>
-Credential <PSCredential>
[<CommonParameters>]Enter-PSSession
[-VMName] <String>
-Credential <PSCredential>
[<CommonParameters>]Description
El cmdlet Enter-PSSession inicia una sesión interactiva con un único equipo remoto. Durante la sesión, los comandos que escriba se ejecutan en el equipo remoto, como si estuviera escribiendo directamente en el equipo remoto. Solo puede tener una sesión interactiva al mismo tiempo.
Normalmente, se utiliza el parámetro ComputerName para especificar el nombre del equipo remoto. Sin embargo, también puede usar una sesión que cree mediante el cmdlet New-PSSession para la sesión interactiva. Sin embargo, no puede usar los cmdlets Disconnect-PSSession, Connect-PSSession o Receive-PSSession para desconectar o volver a conectarse a una sesión interactiva.
Para finalizar la sesión interactiva y desconectar del equipo remoto, use el cmdlet Exit-PSSession o escriba exit.
Ejemplos
Ejemplo 1: Inicio de una sesión interactiva
PS C:\> Enter-PSSession
[localhost]: PS C:\>Este comando inicia una sesión interactiva en el equipo local. El símbolo del sistema cambia para indicar que ahora está ejecutando los comandos en una sesión diferente.
Los comandos que especifique se ejecutan en la nueva sesión y los resultados se devuelven a la sesión predeterminada como texto.
Ejemplo 2: Trabajar con una sesión interactiva
The first command uses the **Enter-PSSession** cmdlet to start an interactive session with Server01, a remote computer. When the session starts, the command prompt changes to include the computer name.
PS C:\> Enter-PSSession -ComputerName Server01
[Server01]: PS C:\>
The second command gets the Windows PowerShell process and redirects the output to the Process.txt file. The command is submitted to the remote computer, and the file is saved on the remote computer.
[Server01]: PS C:\> Get-Process PowerShell > C:\ps-test\Process.txt
The third command uses the **Exit** keyword to end the interactive session and close the connection.
[Server01]: PS C:\> exit
PS C:\>
The fourth command confirms that the Process.txt file is on the remote computer. A **Get-ChildItem** ("dir") command on the local computer cannot find the file.
PS C:\> 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.txtEste comando muestra cómo trabajar en una sesión interactiva con un equipo remoto.
Ejemplo 3: Uso del parámetro Session
PS C:\> $s = New-PSSession -ComputerName Server01
PS C:\> Enter-PSSession -Session $s
[Server01]: PS C:\>Estos comandos usan el parámetro Session de Enter-PSSession para ejecutar la sesión interactiva en una sesión de Windows PowerShell existente (PSSession).
Ejemplo 4: Iniciar una sesión interactiva y especificar los parámetros Port y Credential
PS C:\> Enter-PSSession -ComputerName Server01 -Port 90 -Credential Domain01\User01
[Server01]: PS C:\>Este comando inicia una sesión interactiva con el equipo Server01. Usa el parámetro Port para especificar el puerto y el parámetro Credential para especificar la cuenta de un usuario que tenga permiso para conectarse al equipo remoto.
Ejemplo 5: Detener una sesión interactiva
PS C:\> Enter-PSSession -ComputerName Server01
[Server01]: PS C:\> Exit-PSSession
PS C:\>Este ejemplo muestra cómo iniciar y detener una sesión interactiva. El primer comando usa el cmdlet Enter-PSSession para iniciar una sesión interactiva con el equipo Server01.
El segundo comando usa el cmdlet Exit-PSSession para finalizar la sesión. También puede usar la palabra clave Exit para finalizar la sesión interactiva. Exit-PSSession y Exit tienen el mismo efecto.
Parámetros
-AllowRedirection
Permite redirigir esta conexión a un identificador uniforme de recursos alternativo (URI). De forma predeterminada, no se permite el redireccionamiento.
Cuando se usa el parámetro ConnectionURI, el destino remoto puede devolver una instrucción para redirigir a otro URI. De forma predeterminada, Windows PowerShell no redirige conexiones, pero se puede usar este parámetro para permitir que se redirija la conexión.
De igual modo, se puede limitar el número de veces que la conexión se redirecciona; para ello, hay que cambiar el valor de la opción de sesión MaximumConnectionRedirectionCount. Utilice el parámetro MaximumRedirection del cmdlet New-PSSessionOption o establezca la propiedad MaximumConnectionRedirectionCount de la variable de preferencia $PSSessionOption. El valor predeterminado es 5.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ApplicationName
Escriba el segmento del nombre de aplicación del URI de conexión. Use este parámetro para especificar el nombre de aplicación cuando no utilice el parámetro ConnectionURI en el comando.
El valor predeterminado es el valor de la variable de preferencia $PSSessionApplicationName en el equipo local. Si no se define esta variable de preferencia, el valor predeterminado es WSMAN. Este valor resulta apropiado en la mayoría de los casos. Para obtener más información, consulte about_Preference_Variables.
El servicio WinRM usa el nombre de la aplicación para seleccionar un agente de escucha para atender la solicitud de conexión. El valor de este parámetro debe coincidir con el valor de la propiedad URLPrefix de un agente de escucha en el equipo remoto.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Authentication
Especifica el mecanismo que se utiliza para autenticar las credenciales del usuario. Los valores permitidos para este parámetro son los siguientes:
- Default
- Básico
- Credssp
- Digest
- Kerberos
- Negotiate
- NegotiateWithImplicitCredential
El valor predeterminado es Default.
La autenticación CredSSP solo está disponible en Windows Vista, Windows Server 2008 y versiones posteriores del sistema operativo Windows.
Para obtener más información sobre los valores de este parámetro, vea AuthenticationMechanism Enumeration en MSDN Library.
Precaución: La autenticación del proveedor de soporte técnico de seguridad de credenciales (CredSSP), en la que las credenciales del usuario se pasan a un equipo remoto para autenticarse, está diseñada para comandos que requieren autenticación en más de un recurso, como el acceso a un recurso compartido de red remoto. Este mecanismo el riesgo de seguridad de la operación remota. Si el equipo remoto se ve comprometido, las credenciales que se pasen a él se pueden utilizar para controlar la sesión de red.
| 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
Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para realizar esta acción. Escriba la huella digital del certificado.
Los certificados se usan para la autenticación basada en certificados de cliente. Solo se pueden asignar a cuentas de usuario locales y no funcionan con cuentas de dominio.
Para obtener un certificado, use el comando Get-Item o Get-ChildItem en la unidad Cert: de Windows PowerShell.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ComputerName
Especifica un nombre de equipo. Este cmdlet inicia una sesión interactiva con el equipo remoto especificado. Escriba solo un nombre de equipo. La opción predeterminada es el equipo local.
Escriba el nombre de NetBIOS, la dirección IP o el nombre de dominio completo del equipo. También puede canalizar un nombre de equipo a Enter-PSSession.
Para usar una dirección IP en el valor del parámetro ComputerName , el comando debe incluir el parámetro Credential . Además, el equipo debe estar configurado para el transporte HTTPS, o la dirección IP del equipo remoto debe incluirse en la lista WinRM TrustedHosts en el equipo local. Para obtener instrucciones para agregar un nombre de equipo a la lista TrustedHosts, vea "Cómo agregar un equipo a la lista de hosts de confianza" en about_Remote_Troubleshooting.
Nota: En Windows Vista y versiones posteriores del sistema operativo Windows, para incluir el equipo local en el valor del parámetro ComputerName, debe iniciar Windows PowerShell con la opción Ejecutar como administrador.
| Type: | String |
| Aliases: | Cn |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ConfigurationName
Especifica la configuración de sesión que se usa para la sesión interactiva.
Escriba un nombre de configuración o el URI de un recurso completo para configurar una sesión.
Si especifica solo el nombre de configuración, se antepone el siguiente URI de esquema: https://schemas.microsoft.com/powershell.
La configuración de sesión para una sesión se encuentra en el equipo remoto. Si la configuración de sesión especificada no existe en el equipo remoto, el comando produce un error.
El valor predeterminado es el valor de la variable de preferencia $PSSessionConfigurationName en el equipo local. Si no se establece esta variable de preferencia, el valor predeterminado es Microsoft.PowerShell. Para obtener más información, consulte about_Preference_Variables.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ConnectionUri
Especifica un URI que define el punto de conexión de la sesión. El identificador URI debe ser completo. El formato de esta cadena es:
<Transport>://<ComputerName>:<Port>/<ApplicationName>
El valor predeterminado es el siguiente:
https://localhost:5985/WSMAN
Si no especifica un ConnectionURI, puede usar los parámetros UseSSL, ComputerName, Port y ApplicationName para especificar los valores ConnectionURI.
Los valores válidos para el segmento Transport del identificador URI son HTTP y HTTPS. Si especifica un URI de conexión con un segmento de transporte, pero no especifica un puerto, la sesión se crea mediante puertos estándar: 80 para HTTP y 443 para HTTPS. Para usar los puertos predeterminados para la comunicación remota de Windows PowerShell, especifique el puerto 5985 para HTTP o 5986 para HTTPS.
Si el equipo de destino redirige la conexión a otro URI, Windows PowerShell impide que la redirección se produzca, a menos que se use el parámetro AllowRedirection en el comando.
| Type: | Uri |
| Aliases: | URI, CU |
| Position: | 1 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Credential
Especifica una cuenta de usuario con permiso para realizar esta acción. El valor predeterminado es el usuario actual.
Escriba un nombre de usuario, como User01, Domain01\User01o User@Domain.com, o escriba un objeto PSCredential , como uno devuelto por el cmdlet Get-Credential.
Al escribir un nombre de usuario, este cmdlet le pide una contraseña.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-EnableNetworkAccess
Indica que este cmdlet agrega un token de seguridad interactivo a las sesiones de bucle invertido. El token interactivo permite ejecutar comandos en la sesión de bucle invertido que obtienen datos de otros equipos. Por ejemplo, se puede ejecutar un comando en la sesión que copie los archivos XML de un equipo remoto al equipo local.
Una sesión de bucle invertido es una PSSession que se origina y termina en el mismo equipo. Para crear una sesión de bucle invertido, omita el parámetro ComputerName o establezca su valor en . (punto), localhost o el nombre del equipo local.
De forma predeterminada, las sesiones de bucle invertido se crean mediante un token de red, que podría no proporcionar permisos suficientes para autenticarse en equipos remotos.
El parámetro EnableNetworkAccess tiene efecto solo en las sesiones de bucle invertido. Si usa EnableNetworkAccess al crear una sesión en un equipo remoto, el comando se realiza correctamente, pero el parámetro se omite.
También se puede permitir el acceso remoto a una sesión de bucle invertido con el valor CredSSP del parámetro Authentication, que delega las credenciales de la sesión en otros equipos.
Este parámetro se incorporó en Windows PowerShell 3.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Id
Especifica el identificador de una sesión existente. Enter-PSSession usa la sesión especificada para la sesión interactiva.
Para buscar el identificador de una sesión, use el cmdlet Get-PSSession.
| Type: | Int32 |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-InstanceId
Especifica el identificador de instancia de una sesión existente. Enter-PSSession usa la sesión especificada para la sesión interactiva.
El identificador de instancia es un GUID. Para buscar el identificador de instancia de una sesión, use el cmdlet Get-PSSession . También puede usar los parámetros Session, Name o ID para especificar una sesión existente. O bien, puede usar el parámetro ComputerName para iniciar una sesión temporal.
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Name
Especifica el nombre descriptivo de una sesión existente. Enter-PSSession usa la sesión especificada para la sesión interactiva.
Si el nombre especificado coincide con más de una sesión, se produce un error en el comando. También puede usar los parámetros Session, InstanceID o ID para especificar una sesión existente. O bien, puede usar el parámetro ComputerName para iniciar una sesión temporal.
Para establecer un nombre descriptivo para una sesión, use el parámetro Name del cmdlet New-PSSession .
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Port
Especifica el puerto de red en el equipo remoto que se usa para este comando. Para conectarse a un equipo remoto, este debe estar escuchando en el puerto que usa la conexión. Los puertos predeterminados son 5985, que es el puerto WinRM para HTTP y 5986, que es el puerto winRM para HTTPS.
Antes de usar un puerto alternativo, debe configurar el agente de escucha de WinRM en el equipo remoto para poder escuchar en ese puerto. Utilice los siguientes comandos para configurar el agente de escucha:
1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}
No use el parámetro Port a menos que sea necesario. El puerto establecido en el comando se aplica a todos los equipos o sesiones en los que se ejecuta el comando. Una configuración de puerto alternativo podría impedir que el comando se ejecutara en todos los equipos.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Session
Especifica una sesión de Windows PowerShell (PSSession) que se usará para la sesión interactiva. Este parámetro usa un objeto de sesión. También puede usar los parámetros Name, InstanceID o ID para especificar una PSSession.
Escriba una variable que contenga un objeto de sesión o un comando que cree u obtenga un objeto de sesión, como un comando New-PSSession o Get-PSSession . También puede canalizar un objeto de sesión a Enter-PSSession. Solo puede enviar una PSSession mediante este parámetro. Si escribe una variable que contiene más de una PSSession, se produce un error en el comando.
Cuando se usa Exit-PSSession o la palabra clave EXIT , finaliza la sesión interactiva, pero la PSSession que creó permanece abierta y disponible para su uso.
| Type: | PSSession |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-SessionOption
Establece opciones avanzadas de la sesión. Escriba un objeto SessionOption , como uno que cree mediante el cmdlet New-PSSessionOption , o una tabla hash en la que las claves son nombres de opción de sesión y los valores son valores de opción de sesión.
Los valores predeterminados de las opciones se determinan con el valor de la variable de preferencia $PSSessionOption, si se establece. De lo contrario, los valores predeterminados se establecerán mediante las opciones establecidas en la configuración de sesión.
Los valores de opción de sesión tienen precedencia sobre los valores predeterminados de las sesiones definidos en la variable de preferencia $PSSessionOption y en la configuración de sesión. Sin embargo, no tienen precedencia sobre los valores máximos, las cuotas o los límites establecidos en la configuración de sesión.
Para una descripción de las opciones de la sesión, incluidos los valores predeterminados, vea New-PSSessionOption. Para obtener información sobre la variable de preferencia de $PSSessionOption, consulte about_Preference_Variables. Para obtener más información sobre las configuraciones de sesión, consulte about_Session_Configurations.
| Type: | PSSessionOption |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseSSL
Indica que este cmdlet usa el protocolo Capa de sockets seguros (SSL) para establecer una conexión con el equipo remoto. De forma predeterminada, no se usa SSL.
WS-Management cifra todo el contenido de Windows PowerShell que se transmite por la red. El parámetro UseSSL es una protección adicional que envía los datos a través de una conexión HTTPS en lugar de una conexión HTTP.
Si usa este parámetro, pero SSL no está disponible en el puerto que se usa para el comando, se produce un error en el comando.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VMGuid
Especifica el identificador de una máquina virtual.
| Type: | Guid |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-VMName
Especifica el nombre de una máquina virtual.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
Entradas
System.String, System.Management.Automation.Runspaces.PSSession
Puede canalizar un nombre de equipo, como una cadena o un objeto de sesión a este cmdlet.
Salidas
None
Este cmdlet no devuelve resultados.
Notas
- Para conectarse a un equipo remoto, debe ser miembro del grupo Administradores en el equipo remoto.
- En Windows Vista y versiones posteriores del sistema operativo Windows, para iniciar una sesión interactiva en el equipo local, debe iniciar Windows PowerShell con la opción Ejecutar como administrador.
- Cuando se usa Enter-PSSession, el perfil de usuario en el equipo remoto se usa para la sesión interactiva. Los comandos del perfil de usuario remoto, incluidos los comandos para agregar los complementos de Windows PowerShell y para cambiar el símbolo del sistema, se ejecutan antes de que aparezca el símbolo del sistema remoto.
- Enter-PSSession usa la configuración de referencia cultural de la interfaz de usuario en el equipo local para la sesión interactiva. Para buscar la referencia cultural de la interfaz de usuario local, utilice la variable automática $UICulture.
- Enter-PSSession requiere los cmdlets Get-Command, Out-Default y Exit-PSSession. Si estos cmdlets no se incluyen en la configuración de sesión en el equipo remoto, se producirá un error en los comandos Enter-PSSession .
- A diferencia de Invoke-Command, que analiza e interpreta los comandos antes de enviarlos al equipo remoto, Enter-PSSession envía los comandos directamente al equipo remoto sin interpretación.
- Si la sesión que desea escribir está ocupada procesando un comando, puede haber un retraso antes de que Windows PowerShell responda al comando Enter-PSSession. Se conectará cuando la sesión esté disponible. Para cancelar el comando Enter-PSSession , presione
CTRL+C.