Set-SCUserRole

Set-SCUserRole

Modifies the settings for an existing VMM user role.

Syntax

Parameter Set: Default
Set-SCUserRole [-AddMember <String[]> ] [-AddScope <ClientObject[]> ] [-Description <String> ] [-JobGroup <Guid]> ] [-JobVariable <String> ] [-Name <String> ] [-NATConnectionMaximum <Nullable [System.UInt16]> ] [-NATConnectionMaximumPerUser <Nullable [System.UInt16]> ] [-OnBehalfOfUser <System.String> ] [-OnBehalfOfUserRole <Microsoft.SystemCenter.VirtualMachineManager.UserRole> ] [-Permission <SelfServicePermission[]> ] [-PROTipID <Guid]> ] [-RemoveLibraryStoreSharePath] [-RemoveMember <String[]> ] [-RemoveNATConnectionMaximum] [-RemoveNATConnectionMaximumPerUser] [-RemoveScope <ClientObject[]> ] [-RemoveVMNetworkMaximum] [-RemoveVMNetworkMaximumPerUser] [-RemoveVMNetworkVPNMaximumBandwidthIn] [-RemoveVMNetworkVPNMaximumBandwidthOut] [-RemoveVPNConnectionMaximum] [-RemoveVPNConnectionMaximumPerUser] [-RunAsynchronously] [-ShowPROTips <Boolean]> ] [-UserRole <UserRole> ] [-UserRoleDataPath <String> ] [-VMMServer <ServerConnection> ] [-VMNetworkMaximum <UInt16]> ] [-VMNetworkMaximumPerUser <UInt16]> ] [-VMNetworkVPNMaximumBandwidthInKbps <UInt64]> ] [-VMNetworkVPNMaximumBandwidthOutKbps <UInt64]> ] [-VPNConnectionMaximum <UInt16]> ] [-VPNConnectionMaximumPerUser <UInt16]> ] [ <CommonParameters>]

Detailed Description

The Set-SCUserRole cmdlet modifies the settings for an existing Virtual Machine Manager (VMM) user role. The settings that you can modify depend on the type of VMM user role.

-- VMM Administrator (Administrator)

You can add members to or remove members from the Administrator user role, but you cannot limit the scope of objects that members of this role can manage.

-- Delegated Administrator (DelegatedAdmin)

You can add members to and remove members from, and you can expand or restrict the scope of a Delegated Administrator user role. You can grant members of this user role permission to manage all of the objects in one or more private clouds and host groups and/or allow users to manage all of the objects stored on one or more library servers. Within that framework, you cannot limit the actions that members of the Delegated Administrator user role can perform.

-- Read-Only Administrator (ReadOnlyAdmin)

You can add members to and remove members from, and you can expand or restrict the scope of a Read-Only Administrator User role. However, the members of the user role can only view the properties, status, and job status of the objects within their assigned scope; they cannot modify any of the objects.

-- Self-Service User (SelfServiceUser)

You can add members to or remove members from, and you can expand or limit the scope and actions of members of a Self-Service User role. You can grant members of a self-service user role permission to manage all of the objects in one or more private clouds; permission to create virtual machines; permission to store virtual machines in the stored virtual machine path in the cloud that the virtual machine is on; and permission to use one or more template objects to create virtual machines. Within that framework, you can grant members of a Self-Service User role one or more actions that self-service users can take. You can also limit the number of virtual machines that self-service users can create by setting a quota that applies to each user or to all users collectively.

The actions that you can grant a Self-Service user include the following:

-- AllowLocalAdmin. Grants user local administrator rights on virtual machines.
-- Author. Author virtual machine and service templates.
-- CanShare. Share resources with other Self-Service users.
-- CanReceive. Receive resources from other Self-Service users.
-- Checkpoint. Create and manage virtual machine checkpoints.
-- CheckpointRestoreOnly. Can only restore a checkpoint.
-- Create. Create virtual machines and services from templates. only.
-- CreateFromVHDOrTemplate. Create virtual machines and services from VHD files or templates.
-- PauseAndResume. Pause and resume virtual machines and services.
-- RemoteConnect. Remotely connect to virtual machines.
-- Remove. Remove virtual machines and services.
-- Save. Save virtual machines and services.
-- Shutdown. Shut down virtual machines.
-- Start. Start virtual machines and services.
-- Stop. Stop virtual machines and services.
-- Store. Store virtual machines in a library.

Parameters

-AddMember<String[]>

Adds one or more members to an object that has the concept of members, such as a group. For example, AddMember adds one or more Active Directory domain users or groups to a user role.

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-AddScope<ClientObject[]>

Adds one or more VMM objects to the scope of objects that members of this user role can manage.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Description<String>

States a description for the specified object.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-JobGroup<Guid]>

Specifies an identifier for a series of commands that will run as a set just before the final command that includes the same job group identifier runs.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-JobVariable<String>

Specifies that job progress is tracked and stored in the variable named by this parameter.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Name<String>

Specifies the name of a VMM object.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-NATConnectionMaximum<Nullable [System.UInt16]>

Specifies the maximum number of NAT Connections. Use the parameter to set the quota for the maximum number of NAT Connections per user role.

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-NATConnectionMaximumPerUser<Nullable [System.UInt16]>

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-OnBehalfOfUser<System.String>

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-OnBehalfOfUserRole<Microsoft.SystemCenter.VirtualMachineManager.UserRole>

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Permission<SelfServicePermission[]>

Specifies the actions that members of a Self-Service User role can perform on their virtual machines or services. Valid values are:

-- AllowLocalAdmin
-- Author
-- CanShare
-- CanReceive
-- Checkpoint
-- CheckpointRestoreOnly
-- Create
-- CreateFromVHDOrTemplate
-- PauseAndResume
-- RemoteConnect
-- Remove
-- Save
-- Shutdown
-- Start
-- Stop
-- Store

Giving CreateFromVHDOrTemplate permission also gives Create permission. Giving Checkpoint permission also gives CheckpointRestoreOnly permission.

Example format: -Permission Create,PauseAndResume,Stop

Aliases	VMPermission
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PROTipID<Guid]>

Specifies the ID of the PRO tip that triggered this action. This allows for auditing of PRO tips.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveLibraryStoreSharePath

Indicates that this cmdlet clears the user role data path for a self-service user.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveMember<String[]>

Removes a member from a VMM object that has the concept of membership, such as a group. For example, RemoveMember removes one or more Active Directory domain users or groups from a user role.

Example formats:

-RemoveMember Domain\User

-RemoveMember User

-RemoveMember User@Domain

-RemoveMember Domain\LabGroupAlias

-RemoveMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveNATConnectionMaximum

Indicates that this cmdlet removes the maximum NAT Connections. Use this parameter to remove the quota for the maximum number of NAT Connections per user role.

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveNATConnectionMaximumPerUser

Example formats:

-AddMember Domain\User

-AddMember User

-AddMember User@Domain

-AddMember Domain\LabGroupAlias

-AddMember LabGroupAlias (an Active Directory security group, not an email alias)

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveScope<ClientObject[]>

Removes one or more VMM objects from the scope of objects that members of this user role can manage.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveVMNetworkMaximum

Removes the virtual machine network maximum setting.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveVMNetworkMaximumPerUser

Removes the virtual machine network maximum per user setting.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveVMNetworkVPNMaximumBandwidthIn

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveVMNetworkVPNMaximumBandwidthOut

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveVPNConnectionMaximum

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoveVPNConnectionMaximumPerUser

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RunAsynchronously

Indicates that the job runs asynchronously so that control returns to the command shell immediately.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ShowPROTips<Boolean]>

Indicates whether to show PRO tips. This parameter only applies to Self-Service User roles.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-UserRole<UserRole>

Specifies a user role object. A UserRole on which the max limit of NAT connection to be set.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	True (ByValue)
Accept Wildcard Characters?	false

-UserRoleDataPath<String>

Specifies the path to a library share that members of a Self-Service User role can use to upload their data.

Example format: -UserRoleDataPath "\\LibraryServerName\LibraryShareName"

Aliases	LibraryStoreSharePath
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VMMServer<ServerConnection>

Specifies a VMM server object.

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VMNetworkMaximum<UInt16]>

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VMNetworkMaximumPerUser<UInt16]>

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VMNetworkVPNMaximumBandwidthInKbps<UInt64]>

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VMNetworkVPNMaximumBandwidthOutKbps<UInt64]>

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VPNConnectionMaximum<UInt16]>

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VPNConnectionMaximumPerUser<UInt16]>

Aliases	none
Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see    about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

Outputs

The output type is the type of the objects that the cmdlet emits.

• UserRole

Examples

Example 1: Add the specified users to the VMM Administrator user role

The first command gets the user role object named Administrator, and then stores the object in the $UserRole variable.

The second command adds User1 and User2, both members of the Contoso.com domain, to the Administrator user role.

PS C:\> $UserRole = Get-SCUserRole -Name "Administrator"
PS C:\> Set-SCUserRole -UserRole $UserRole -AddMember Contoso\User1,Contoso\User2

Example 2: Add the specified users to the Administrator role in a single command

This command gets all user role objects from VMMServer01, selects the user role objects whose profile is Administrator, and then adds User3 to the Administrator user role.

PS C:\> Get-SCUserRole -VMMServer "VMMServer01.Contoso.com" | where { $_.Profile -eq "Administrator" } | Set-SCUserRole -AddMember Contoso\User3

Example 3: Modify an existing self-service user role by adding a cloud to its scope

The first command gets the cloud object named Cloud02, and then stores the object in the $Cloud variable.

The second command gets the user role object named ContosoSelfServiceUsers, and then stores the object in the $UserRole profile.

The last command modifies the scope of the user role stored in $UserRole by adding the cloud stored in $Cloud to its scope.

PS C:\> $Cloud = Get-SCCloud -Name "Cloud02"
PS C:\> $UserRole = Get-SCUserRole -Name "ContosoSelfServiceUsers"
PS C:\> Set-SCUserRole -UserRole $UserRole -AddScope $Cloud

Example 4: Remove the specified user from the Administrator user role

The first command gets the user role object named Administrator, and then stores the object in the $UserRole variable.

The second command removes User01, who is a member of the Contoso.com domain, from the Administrator user role.

PS C:\> $UserRole = Get-SCUserRole -Name "Administrator"
PS C:\> Set-SCUserRole -UserRole $UserRole -RemoveMember Contoso\User1

Example 5: Add a cloud to the scope of a self-service user role

The first command gets the cloud object named Cloud03 and stores the object in the $Cloud variable.

The second command gets the user role object named ContosoSelfServiceUsers and then passes the user role object to the Set-SCUserRole cmdlet. The Set-SCUserRole cmdlet adds the cloud stored in $Cloud to the user role.

PS C:\> $Cloud = Get-SCCloud -Name "Cloud03"
PS C:\> Get-SCUserRole -Name "ContosoSelfServiceUsers" | Set-SCUserRole -AddScope $Cloud

Example 6: Modify what actions members of a self-service user role can take on their virtual machines.:

The first command gets the user role object on VMMServer01 named ContosoSelfServiceUsers, and then stores the object in the $UserRole variable.

The second command modifies the permissions for members of the user role stored in $UserRole to allow Creation, PauseAndResume, Stop, AllowLocalAdmin and Store permissions.

To list all available permissions that you can specify for self-service users, type:

PS C:\> [enum]::GetValues([Microsoft.VirtualManager.Remoting.SelfServicePermission])

You can specify the following permissions with the Permission parameter:

-- Create. Create virtual machines and services from VHDs or Templates.
-- PauseAndResume. Pause and resume virtual machines and services.
-- Start. Start virtual machines and services.
-- Stop. Stop virtual machines and services.
-- AllowLocalAdmin. Act as local Administrator on virtual machines.
-- RemoteConnect. Access virtual machines remotely.
-- Remove. Remove virtual machines and services.
-- Shutdown. Shut down virtual machines.
-- Checkpoint. Create and manage virtual machine checkpoints.
-- Store. Store virtual machines in the library.
-- Save. Save virtual machines and services.
-- Author. Author virtual machine and service templates.
-- CanShare. Share resources with other self-service users.
-- CanReceive. Receive resources from other self-service users.
-- CreateFromVHDorTemplate Create virtual machines and services from VHDs or Templates.
-- CheckpointRestoreOnly. Restore to but cannot create virtual machine checkpoints.

PS C:\> $UserRole = Get-SCUserRole -VMMServer "VMMServer01.Contoso.com" -Name "ContosoSelfServiceUsers"
PS C:\> Set-SCUserRole -UserRole $UserRole -Permission "Create,PauseAndResume,Stop,AllowLocalAdmin,Store"

Example 7: Set the maximum NAT connections for a User Role

This first command gets a user role named TenantAdmin and stores it in the variable named $UserRole. The second command specifies a limit for the number of NAT connections a Tenant Admin can create on a particular user role to 5.

PS C:\> $UserRole = Get-SCUserRole -Name "TenantAdmin"
PS C:\> Set-SCUserRole –UserRole $UserRole –NATConnectionMaximum 5

Example 8: Remove the maximum NAT connections for a User Role

This first command gets a user role named TenantAdmin and stores it in the variable named $UserRole. The second command removes all NAT connections in the User Role stored in the $UserRole variable.

PS C:\> $UserRole = Get-SCUserRole -Name "TenantAdmin"
Set-SCUserRole –UserRole $UserRole –RemoveNATConnectionMaximum

Related topics

Get-SCUserRole

Grant-SCResource

New-SCUserRole

Remove-SCUserRole

Revoke-SCResource