New-PSSession

Crea una conexión persistente a un equipo local o remoto.

Syntax

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

Description

El New-PSSession cmdlet crea una sesión de PowerShell (PSSession) en un equipo local o remoto. Al crear una PSSession, PowerShell establece una conexión persistente al 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 Invoke-Command cmdlet . Para usar PSSession para interactuar directamente con un equipo remoto, use el Enter-PSSession cmdlet . Para obtener más información, consulte about_PSSessions.

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 , PowerShell crea una conexión temporal que se usa para el comando y, a continuación, se cierra.

Ejemplos

Ejemplo 1: Crear una sesión en el equipo local

$s = New-PSSession

Este comando crea una nueva PSSession en el equipo local y guarda la PSSession en la $s variable .

Ahora puede usar esta PSSession para ejecutar comandos en el equipo local.

Ejemplo 2: Crear una sesión en un equipo remoto

$Server01 = New-PSSession -ComputerName Server01

Este comando crea una nueva PSSession en el equipo Server01 y la guarda en la $Server01 variable .

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: Crear sesiones en varios equipos

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

Este 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: $s1, $s2, $s3. Asigna la PSSession Server01 a $s1, la PSSession Server02 a $s2y server03 PSSession a $s3.

Al asignar varios objetos a una serie de variables, 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: Creación de una sesión con un puerto especificado

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

Este comando crea una nueva PSSession en el equipo Server01 que se conecta al puerto 8081 del servidor 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 obtener más información, consulte la descripción del parámetro Port .

Ejemplo 5: Creación de una sesión basada en una sesión existente

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

Este 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 $s variable . Usa las credenciales del Domain1\Admin01 usuario para completar el comando.

Ejemplo 6: Creación de una sesión con un ámbito global en un dominio diferente

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

En 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 psSession en una variable que se convierta en un ámbito global. En este caso, la $s variable 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 al de la cuenta de usuario, se especifica el nombre completo del equipo junto con las credenciales del usuario.

Ejemplo 7: Crear sesiones para muchos equipos

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

Este comando crea una PSSession en cada uno de los 200 equipos enumerados en el Servers.txt archivo y almacena la PSSession resultante en la $rs variable . Los objetos PSSession tienen un límite de limitación 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: Creación de una sesión mediante un URI

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

Este comando crea una PSSession en el equipo Server01 y la almacena en la $s variable . 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

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

Estos 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 Servers.txt archivo. Usa el New-PSSession cmdlet para crear la PSSession. El valor del parámetro ComputerName es un comando que usa el Get-Content cmdlet para obtener la lista de nombres de equipo del Servers.txt archivo.

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 $s variable .

El segundo comando usa el parámetro AsJob del Invoke-Command cmdlet 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 los trabajos en segundo plano de PowerShell, consulte about_Jobs y about_Remote_Jobs.

Ejemplo 10: Creación de una sesión para un equipo mediante su URI

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

Este comando crea objetos PSSession que se conectan a un equipo especificado por un URI en lugar de un nombre de equipo.

Ejemplo 11: Crear una opción de sesión

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

En 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 New-PSSessionOption cmdlet para crear una opción de sesión. Guarda el objeto SessionOption resultante en la $so variable .

El segundo comando usa la opción en una nueva sesión. El comando usa el New-PSSession cmdlet para crear una nueva sesión. El valor del parámetro SessionOption es el objeto SessionOption de la $so variable .

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 Conectar ionURI, el destino remoto puede devolver una instrucción para redirigir a otro URI. De forma predeterminada, PowerShell no redirige las conexiones, pero puede usar este parámetro para permitir que redirija la conexión.

También puede limitar el número de veces que se redirige la conexión cambiando el valor de la opción de sesión Maximum Conectar ionRedirectionCount. Use el parámetro MaximumRedirection del New-PSSessionOption cmdlet o establezca la propiedad Maximum Conectar ionRedirectionCount de la variable de preferencia $PSSessionOption. El valor predeterminado es 5.

Type:SwitchParameter
Position:Named
Default value:False
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 la aplicación cuando no use el parámetro Conectar ionURI en el comando .

El valor predeterminado es el valor de la $PSSessionApplicationName variable de preferencia 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
  • Basic
  • 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 (enumeración).

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 Get-Item comando o Get-ChildItem en la unidad de PowerShell Cert: .

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, localhosto 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, consulte "Cómo agregar un equipo a la lista de hosts de confianza" about_Remote_Troubleshooting.

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: http://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 $PSSessionConfigurationName variable de preferencia 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:

http://localhost:5985/WSMAN

Si no especifica un Conectar URI, puede usar los parámetros UseSSL, ComputerName, Port y ApplicationName para especificar los valores de Conectar IONURI.

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 con puertos estándar: 80 para HTTP y 443 PARA HTTPS. Para usar los puertos predeterminados para la comunicación remota de PowerShell, especifique el puerto 5985 para HTTP o 5986 HTTPS.

Si el equipo de destino redirige la conexión a un URI diferente, PowerShell impide el redireccionamiento a menos que 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

-ContainerId

Especifica una matriz de identificadores de contenedores. Este cmdlet inicia una sesión interactiva con cada uno de los contenedores especificados. Use el docker ps comando para obtener una lista de identificadores de contenedor. Para obtener más información, consulte la ayuda para el comando docker ps .

Type:String[]
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Credential

Especifica una cuenta de usuario que tiene permiso para realizar esta acción. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto PSCredential generado por el Get-Credential cmdlet . Si escribe un nombre de usuario, se le pedirá que escriba la contraseña.

Las credenciales se almacenan en un objeto PSCredential y la contraseña se almacena como SecureString.

Nota:

Para obtener más información sobre la protección de datos SecureString , consulte ¿Cómo es secure is SecureString?.

Type:PSCredential
Position:Named
Default value:Current user
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 dot (.), localhosto el nombre del equipo local.

De forma predeterminada, este cmdlet crea sesiones de bucle invertido mediante un token de red, lo que podría no proporcionar permiso suficiente para autenticarse en equipos remotos.

El parámetro EnableNetworkAccess solo es efectivo en 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 CredSSP valor 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, vea Disconnect-PSSession.

Este parámetro se introdujo en PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:False
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 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

-RunAsAdministrator

Indica que la PSSession se ejecuta como administrador.

Type:SwitchParameter
Position:Named
Default value:False
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 New-PSSession comando o Get-PSSession .

Los objetos PSSession resultantes tienen el mismo nombre de equipo, nombre de aplicación, URI de conexión, puerto, nombre de configuración, límite de limitación y valor de Capa de sockets seguros (SSL) que los originales, pero tienen un nombre para mostrar diferente, identificador e identificador de instancia (GUID).

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 New-PSSessionOption cmdlet 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 mediante el valor de la $PSSessionOption variable de preferencia, 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 prioridad sobre los valores predeterminados de las sesiones establecidas en la $PSSessionOption variable de preferencia y en la configuración de la 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 incluye los valores predeterminados, consulte New-PSSessionOption. Para obtener información sobre la $PSSessionOption variable de preferencia, consulte about_Preference_Variables. Para más información sobre las configuraciones de sesión, vea 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 omite este parámetro o especifica un valor de 0 (cero), se usa 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 al equipo remoto. De forma predeterminada, no se usa SSL.

WS-Management cifra todo el contenido de PowerShell transmitido a través de 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:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-VMId

Especifica una matriz de identificadores de máquina virtual. Este cmdlet inicia una sesión interactiva de PowerShell Direct con cada una de las máquinas virtuales especificadas. Para más información, consulte Automatización y administración de máquinas virtuales mediante PowerShell.

Use Get-VM para ver las máquinas virtuales que están disponibles en el host de Hyper-V.

Type:Guid[]
Aliases:VMGuid
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-VMName

Especifica una matriz de nombres de máquinas virtuales. Este cmdlet inicia una sesión interactiva de PowerShell Direct con cada una de las máquinas virtuales especificadas. Para más información, consulte Automatización y administración de máquinas virtuales mediante PowerShell.

Use Get-VM para ver las máquinas virtuales que están disponibles en el host de Hyper-V.

Type:String[]
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

Entradas

String

Puede canalizar una cadena a este cmdlet.

System.URI

Puede canalizar un URI a este cmdlet.

PSSession

Puede canalizar un objeto de sesión a este cmdlet.

Salidas

PSSession

Notas

Windows PowerShell incluye los siguientes alias para New-PSSession:

  • nsn

  • Este cmdlet usa la infraestructura de comunicación remota de PowerShell. Para usar este cmdlet, el equipo local y los equipos remotos deben configurarse para la comunicación remota de PowerShell. Para obtener más información, consulte about_Remote_Requirements.

  • Para crear una PSSession en el equipo local, inicie PowerShell con la opción Ejecutar como administrador .

  • Cuando haya terminado con PSSession, use el Remove-PSSession cmdlet para eliminar PSSession y liberar sus recursos.