New-PSSession
Crea una conexión persistente a un equipo local o remoto.
Syntax
New-PSSession
[[-ComputerName] <String[]>]
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-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
[[-Session] <PSSession[]>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ThrottleLimit <Int32>]
[<CommonParameters>]Description
El cmdlet New-PSSession crea una sesión de Windows PowerShell (PSSession) en un equipo local o remoto. Al crear una PSSession, Windows PowerShell establece una conexión persistente con el equipo remoto.
Use una PSSession para ejecutar varios comandos que comparten datos, como una función o el valor de una variable. Para ejecutar comandos en una PSSession, use el cmdlet Invoke-Command. Para usar PSSession para interactuar directamente con un equipo remoto, use el cmdlet Enter-PSSession. Para obtener más información, consulte about_PSSessions (https://go.microsoft.com/fwlink/?LinkID=135181).
Puede ejecutar comandos en un equipo remoto sin crear una PSSession mediante los parámetros ComputerName de Enter-PSSession o Invoke-Command. Cuando se usa el parámetro ComputerName, Windows PowerShell crea una conexión temporal que se usa para el comando y, luego, se cierra.
Ejemplos
Ejemplo 1: Create una sesión en el equipo local
PS C:\> $s = New-PSSessionEste comando crea una nueva PSSession en el equipo local y guarda la PSSession en la variable $s.
Ahora puede usar esta PSSession para ejecutar comandos en el equipo local.
Ejemplo 2: Create una sesión en un equipo remoto
PS C:\> $Server01 = New-PSSession -ComputerName Server01Este comando crea una nueva PSSession en el equipo Server01 y la guarda en la variable $Server 01.
Al crear varios objetos PSSession , asígnelos a variables con nombres útiles. Esto le ayudará a administrar los objetos PSSession en comandos posteriores.
Ejemplo 3: Create sesiones en varios equipos
PS C:\> $s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03Este comando crea tres objetos PSSession , uno en cada uno de los equipos especificados por el parámetro ComputerName .
El comando usa el operador de asignación (=) para asignar los nuevos objetos PSSession a variables: $s 1, $s 2, $s 3. Asigna la PSSession Server01 a $s 1, la PSSession Server02 a $s 2 y la PSSession Server03 a $s 3.
Al asignar varios objetos a una serie de variables, Windows PowerShell asigna cada objeto a una variable de la serie respectivamente. Si hay más objetos que variables, todos los objetos restantes se asignan a la última variable. Si hay más variables que objetos, las variables restantes están vacías (null).
Ejemplo 4: Create una sesión con un puerto especificado
PS C:\> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12Este comando crea una nueva PSSession en el equipo Server01 que se conecta al puerto de servidor 8081 y usa el protocolo SSL. La nueva PSSession usa una configuración de sesión alternativa denominada E12.
Antes de configurar el puerto, debe configurar el agente de escucha de WinRM en el equipo remoto para que escuche en el puerto 8081. Para más información, vea la descripción del parámetro Port.
Ejemplo 5: Create una sesión basada en una sesión existente
PS C:\> New-PSSession -Session $s -Credential Domain01\User01Este comando crea una PSSession con las mismas propiedades que una PSSession existente. Puede usar este formato de comando cuando se agoten los recursos de una PSSession existente y se necesita una nueva PSSession para descargar parte de la demanda.
El comando usa el parámetro Session de New-PSSession para especificar la PSSession guardada en la variable $s. Usa las credenciales del usuario Domain1\Admin01 para completar el comando.
Ejemplo 6: Create una sesión con un ámbito global en un dominio diferente
PS C:\> $global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01En este ejemplo se muestra cómo crear una PSSession con un ámbito global en un equipo de otro dominio.
De forma predeterminada, los objetos PSSession creados en la línea de comandos se crean con el ámbito local y los objetos PSSession creados en un script tienen ámbito de script.
Para crear una PSSession con ámbito global, cree una nueva PSSession y, a continuación, almacene la PSSession en una variable que se convierta en un ámbito global. En este caso, la variable $s se convierte en un ámbito global.
El comando usa el parámetro ComputerName para especificar el equipo remoto. Dado que el equipo está en un dominio diferente de la cuenta de usuario, se especifica el nombre completo del equipo junto con las credenciales del usuario.
Ejemplo 7: sesiones de Create para muchos equipos
PS C:\> $rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50Este comando crea una PSSession en cada uno de los 200 equipos enumerados en el archivo Servers.txt y almacena la PSSession resultante en la variable $rs. Los objetos PSSession tienen un límite de 50.
Puede usar este formato de comando cuando se almacenan los nombres de equipos en una base de datos, hoja de cálculo, archivo de texto u otro formato convertible de texto.
Ejemplo 8: Create una sesión mediante un URI
PS C:\> $s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01Este comando crea una PSSession en el equipo Server01 y la almacena en la variable $s. Usa el parámetro URI para especificar el protocolo de transporte, el equipo remoto, el puerto y una configuración de sesión alternativa. También usa el parámetro Credential para especificar una cuenta de usuario que tenga permiso para crear una sesión en el equipo remoto.
Ejemplo 9: Ejecución de un trabajo en segundo plano en un conjunto de sesiones
PS C:\> $s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJobEstos comandos crean un conjunto de objetos PSSession y, a continuación, ejecutan un trabajo en segundo plano en cada uno de los objetos PSSession .
El primer comando crea una nueva PSSession en cada uno de los equipos enumerados en el archivo Servers.txt. Usa el cmdlet New-PSSession para crear la PSSession. El valor del parámetro ComputerName es un comando que usa el cmdlet Get-Content para obtener la lista de nombres de equipo del archivo Servers.txt.
El comando usa el parámetro Credential para crear los objetos PSSession que tienen el permiso de un administrador de dominio y usa el parámetro ThrottleLimit para limitar el comando a 16 conexiones simultáneas. El comando guarda los objetos PSSession en la variable $s.
El segundo comando usa el parámetro AsJob del cmdlet Invoke-Command para iniciar un trabajo en segundo plano que ejecuta un Get-Process PowerShell comando en cada uno de los objetos PSSession de $s.
Para obtener más información sobre Windows PowerShell trabajos en segundo plano, consulte about_Jobs y about_Remote_Jobs.
Ejemplo 10: Create una sesión de un equipo mediante su URI
PS C:\> New-PSSession -ConnectionURI https://management.exchangelabs.com/ManagementEste comando crea un objeto PSSession que se conecta a un equipo especificado por un URI en lugar de un nombre de equipo.
Ejemplo 11: Create una opción de sesión
PS C:\> $so = New-PSSessionOption -SkipCACheck
PS C:\> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01En este ejemplo se muestra cómo crear un objeto de opción de sesión y usar el parámetro SessionOption .
El primer comando usa el cmdlet New-PSSessionOption para crear una opción de sesión. Guarda el objeto SessionOption resultante en la variable $so.
El segundo comando usa la opción en una nueva sesión. El comando usa el cmdlet New-PSSession para crear una nueva sesión. El valor del parámetro SessionOption es el objeto SessionOption en la variable $so.
Parámetros
-AllowRedirection
Indica que este cmdlet permite el redireccionamiento de esta conexión a un identificador uniforme de recursos (URI) alternativo.
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 las conexiones, pero puede usar este parámetro para habilitarla para redirigir 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 aplicación para seleccionar un agente de escucha que atienda 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.
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 de 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 una matriz de nombres de equipos. Este cmdlet crea una conexión persistente (PSSession) al equipo especificado. Si escribe varios nombres de equipo, New-PSSession crea varios objetos PSSession , uno para cada equipo. La opción predeterminada es el equipo local.
Escriba el nombre de NetBIOS, una dirección IP o un nombre de dominio completo de uno o más equipos remotos. Para especificar el equipo local, escriba el nombre del equipo, localhost o un punto (.). Cuando el equipo esté en un dominio diferente al del usuario, se requiere el nombre de dominio completo. También puede canalizar un nombre de equipo, entre comillas, a New-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 (https://go.microsoft.com/fwlink/?LinkID=135188).
Para incluir el equipo local en el valor del parámetro ComputerName, inicie Windows PowerShell mediante la opción Ejecutar como administrador.
| Type: | String[] |
| Aliases: | Cn |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ConfigurationName
Especifica la configuración de sesión que se usa para la nueva PSSession.
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 transporte, pero no especifica un puerto, la sesión se crea con 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: | 0 |
| Default value: | None |
| Required: | True |
| 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\User01 o 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, este cmdlet crea sesiones de bucle invertido 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 puede habilitar el acceso remoto en una sesión de bucle invertido mediante el valor CredSSP del parámetro Authentication , que delega las credenciales de sesión en otros equipos.
Para proteger el equipo contra el acceso malintencionado, las sesiones de bucle invertido desconectadas que tienen tokens interactivos, que son los creados mediante el parámetro EnableNetworkAccess , solo se pueden volver a conectar desde el equipo en el que se creó la sesión. Las sesiones desconectadas que usan la autenticación CredSSP se pueden volver a conectar desde otros equipos. Para obtener más información, consulte Disconnect-PSSession.
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 |
-Name
Especifica un nombre descriptivo para PSSession.
Puede usar el nombre para hacer referencia a PSSession cuando use otros cmdlets, como Get-PSSession y Enter-PSSession. El nombre no tiene que ser único en el equipo o en la sesión actual.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Port
Especifica el puerto de red del equipo remoto que se usa para esta conexión. 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 otro puerto, debe configurar el agente de escucha de WinRM en el equipo remoto para que escuche 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 matriz de objetos PSSession que este cmdlet usa como modelo para la nueva PSSession. Este parámetro crea nuevos objetos PSSession que tienen las mismas propiedades que los objetos PSSession especificados .
Escriba una variable que contenga los objetos PSSession o un comando que crea u obtiene los objetos PSSession , como un comando New-PSSession o Get-PSSession.
Los objetos PSSession resultantes tienen el mismo nombre de equipo, el nombre de la aplicación, el URI de conexión, el puerto, el nombre de configuración, el límite de limitación y el valor de capa de sockets seguros (SSL) que los originales, pero tienen un nombre para mostrar, un identificador y un identificador de instancia (GUID) diferentes.
| Type: | PSSession[] |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-SessionOption
Especifica opciones avanzadas para 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 obtener una descripción de las opciones de sesión que incluyen los valores predeterminados, consulte 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 |
-ThrottleLimit
Especifica el número máximo de operaciones simultáneas que se pueden establecer para ejecutar este comando. Si se omite este parámetro o especifica un valor 0 (cero), se utiliza el valor predeterminado, 32.
El límite solo se aplica al comando actual, no a la sesión ni al equipo.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseSSL
Indica que este cmdlet usa el protocolo 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 ofrece 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 |
Entradas
System.String, System.URI, System.Management.Automation.Runspaces.PSSession
Puede canalizar una cadena, un URI o un objeto de sesión a este cmdlet.
Salidas
Notas
Este cmdlet usa la infraestructura de comunicación remota de Windows PowerShell. Para usar este cmdlet, el equipo local y los equipos remotos deben configurarse para la comunicación remota de Windows PowerShell. Para obtener más información, consulte about_Remote_Requirements.
Para crear una PSSession en el equipo local, inicie Windows PowerShell con la opción Ejecutar como administrador.
Cuando haya terminado con PSSession, use el cmdlet Remove-PSSession para eliminar psSession y liberar sus recursos.