vitoolkitextensions Wiki & Documentation Rss Feed

Updated Wiki: examples

LucD — Thu, 01 Jan 2009 10:49:20 GMT

Examples

Roles, privileges and permissions
Guest OS ids

Updated Wiki: Guest OS ids

LucD — Thu, 01 Jan 2009 10:46:58 GMT

Guest OS ids
See Carter's entry in his VI Toolkit (for Windows) blog.

Updated Wiki: examples

LucD — Thu, 01 Jan 2009 10:42:54 GMT

Examples

Roles, privileges and permissions
Guest OS ids

Updated Wiki: Roles, privileges and permissions

LucD — Thu, 01 Jan 2009 10:40:44 GMT

Roles, privileges and permissions
The security in virtual infrastructure (VI) is organised around

privileges, specific rights on ESX Servers, Virtual Machines, or other VI objects. For example the right to start a Virtual Machine
roles, are objects that group specific rights together for easier assignment. The Virtual Machine User role has several rights to intercat with a guest.
permissions, is where you combine users, or groups, with specific roles.

To see all the available privileges in VI you can do:

PS C:\> Get-TkeAllPriviliges
 
Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read
ManageCustomFields                                               False Global                             Global.ManageCustomFields

This advanced function returns an array of AuthorizationPrivilege objects.
See the API Reference guide for an explanation of the properties.

To see the roles that are currently defined in the VI you can do:

PS C:\> Get-TkeRoles
 
 
Name      : NoAccess
Label     : No Access
Summary   : Used for restricting granted access
RoleId    : -5
System    : True
Privilege :
 
Name      : Anonymous
Label     : Anonymous
Summary   : Not logged-in user (cannot be granted)
RoleId    : -4
System    : True
Privilege : {System.Anonymous}
 
Name      : View
Label     : View
Summary   : Visibility access (cannot be granted)
RoleId    : -3
System    : True
Privilege : {System.Anonymous, System.View}

VI comes with a number of pre-defined roles.
These pre-defined roles all have a negative RoleId number and cannot be changed.

To see the privileges that are grouped under a specific role you could do

PS C:\> Get-TkeRoles | where {$_.Name -eq "ReadOnly"} | select -ExpandProperty Privilege
System.Anonymous
System.Read
System.View

but there is a specific advanced function to do just that

PS C:\> Get-TkeRolePrivileges -name "readonly"
 
Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read

Note that the names of the roles do not always correspond literaly with the role names you see in the VI Client.

To create a new role with a specific set of privileges you can do

PS C:\> New-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.PowerOn","VirtualMachine.Interact.PowerOff"
110

The advanced function returns the roleId of the new role.

Note that the privilege Ids are case-sensitive !

You can also start from one of the pre-defined roles.
For that it suffices to clone the role.

PS C:\> Clone-TkeRole "VirtualMachineUser" "My Cloned Role"
113

This advanced function will return the roleId of the new role, similar to the New-TkeRole advanced function.

If you want to make changes to the privileges assigned to a user-defined role (remember, the roles with the positive roleId numbers) you can do

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Suspend"

The Set-TkeRol cmdlet has a parameter, called -append, which allows you to specify if the privileges need to be added (-append:$true) to the existing privileges or need to replace (-append:$false) the existing privileges.

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Reset" -append:$true

You can also change the name of a user-defined role

PS C:\> Set-TkeRole -name "My new role" -newName "A new name for the role"

If a role becomes obsolete, you can remove it like this

PS C:\> Remove-TkeRole -name "A new name for the role"

As a failsafe this cmdlet has a switch, called -FailIfUsed, which prohibits the removal of the role if the role is used in a permission.
The default for this switch is -FailIfUsed:$true.

PS C:\> Remove-TkeRole -name "A new name for the role" -FailIfUsed:$false

Once you have the roles set up like you want, you can start assigning permissions.

A permission can be used on practicaly all of the VI objects.
As a guideline, if the object has a Permissions tab in the VI Client, you assign permissions to it.

To set a permission, use the Set-TkePermissions advanced function.
The -permission parameter accepts one or more (an array) Permission object(s).
See the API Reference guide for an explanation of the properties.

In this example we assign the privileges, defined in the ReadOnly role, to the user account Test\Guest.
The permission will only be applied to the object itself, not to any of it's cildren.

PS C:\> $MyPermission = New-Object VMware.Vim.Permission
PS C:\> $MyPermission.principal = "Test\Guest"
PS C:\> $MyPermission.group = $false
PS C:\> $myPermission.propagate = $false
PS C:\> $MyPermission.RoleId = (Get-TkeRoles | Where-Object {$_.Name -eq "ReadOnly"} | % {$_.RoleId})
PS C:\> Get-VM PC2 | Set-TkePermissions -permission $myPermission
PS C:\> Get-VM PC2 | Get-TkePermissions
 
Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly

The example also showed the use of the Get-TkePermissions cmdlet.
This will list all permissions that are set on a VI object.

If you also want to see the permissions that were inherited for that object, you need to use the -inherited parameter.

PS C:\> Get-VM PC2 | Get-TkePermissions -inherited:$true
 
 
Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly
 
Entity    : Datacenters
Group     : True
Principal : TEST\Domain Admins
Propagate : True
Role      : Admin

The removal of a permission is rather straight-forward.

PS C:\> Get-VM PC2 | Remove-TkePermissions -principal "Test\Guest"

Updated Wiki: examples

LucD — Thu, 01 Jan 2009 10:40:19 GMT

Examples

Roles, privileges and permissions

Updated Wiki: examples

LucD — Wed, 31 Dec 2008 19:43:32 GMT

Roles, privileges and permissions
The security in virtual infrastructure (VI) is organised around

privileges, specific rights on ESX Servers, Virtual Machines, or other VI objects. For example the right to start a Virtual Machine
roles, are objects that group specific rights together for easier assignment. The Virtual Machine User role has several rights to intercat with a guest.
permissions, is where you combine users, or groups, with specific roles.

To see all the available privileges in VI you can do:

PS C:\> Get-TkeAllPriviliges
 
Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read
ManageCustomFields                                               False Global                             Global.ManageCustomFields

PS C:\> Get-TkeRoles
 
 
Name      : NoAccess
Label     : No Access
Summary   : Used for restricting granted access
RoleId    : -5
System    : True
Privilege :
 
Name      : Anonymous
Label     : Anonymous
Summary   : Not logged-in user (cannot be granted)
RoleId    : -4
System    : True
Privilege : {System.Anonymous}
 
Name      : View
Label     : View
Summary   : Visibility access (cannot be granted)
RoleId    : -3
System    : True
Privilege : {System.Anonymous, System.View}

PS C:\> Get-TkeRoles | where {$_.Name -eq "ReadOnly"} | select -ExpandProperty Privilege
System.Anonymous
System.Read
System.View

but there is a specific advanced function to do just that

PS C:\> Get-TkeRolePrivileges -name "readonly"
 
Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read

Note that the names of the roles do not always correspond literaly with the role names you see in the VI Client.

To create a new role with a specific set of privileges you can do

PS C:\> New-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.PowerOn","VirtualMachine.Interact.PowerOff"
110

PS C:\> Clone-TkeRole "VirtualMachineUser" "My Cloned Role"
113

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Suspend"

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Reset" -append:$true

You can also change the name of a user-defined role

PS C:\> Set-TkeRole -name "My new role" -newName "A new name for the role"

If a role becomes obsolete, you can remove it like this

PS C:\> Remove-TkeRole -name "A new name for the role"

As a failsafe this cmdlet has a switch, called -FailIfUsed, which prohibits the removal of the role if the role is used in a permission.
The default for this switch is -FailIfUsed:$true.

PS C:\> Remove-TkeRole -name "A new name for the role" -FailIfUsed:$false

PS C:\> $MyPermission = New-Object VMware.Vim.Permission
PS C:\> $MyPermission.principal = "Test\Guest"
PS C:\> $MyPermission.group = $false
PS C:\> $myPermission.propagate = $false
PS C:\> $MyPermission.RoleId = (Get-TkeRoles | Where-Object {$_.Name -eq "ReadOnly"} | % {$_.RoleId})
PS C:\> Get-VM PC2 | Set-TkePermissions -permission $myPermission
PS C:\> Get-VM PC2 | Get-TkePermissions
 
Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly

PS C:\> Get-VM PC2 | Get-TkePermissions -inherited:$true
 
 
Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly
 
Entity    : Datacenters
Group     : True
Principal : TEST\Domain Admins
Propagate : True
Role      : Admin

The removal of a permission is rather straight-forward.

PS C:\> Get-VM PC2 | Remove-TkePermissions -principal "Test\Guest"

Updated Wiki: guidelines

cartershanklin — Wed, 31 Dec 2008 18:25:27 GMT

Guidelines for Community Extensions Advanced Functions

(Please note, under construction)

Naming Conventions

PowerShell's naming convention is Verb-SingularNoun. For example Get-VM where Get is a verb and VM is a singular noun. The singular noun convention means you don't define a cmdlet like Get-VMsOnHost since this introduces two separate concepts (the VMs and the Hosts they run on). Additionally, PowerShell defines a set of recommended verbs that you are encouraged to use.

There are exceptions to these rules, both in PowerShell products produced by Microsoft and other parties. In general though, it's best to stick as close to this basic naming guideline as possible.

In the Community Extensions there is an additional constraint placed on naming guidelines: to help identify commands as coming from the Community Extensions they must be prefaced with "Tke", which stands for "Toolkit Extensions".

Examples:
* Get-TkeVmxEntries
* Restart-TkeVMHost

If you are writing a Set-* function, you are encouraged to also write a Get-* cmdlet that will produce objects for the Set-* function to operate upon. Get-* cmdlets are important for selecting the objects on which users wish to operate, as well as other functions like creating reports.

Capitalization should follow the recommended practices for .NET code.

Defining Parameters

A full explanation of defining parameters can be found by typing help aboutfunctionsadvanced_parameters at your PowerShell prompt. For now here's an example with some commentary:

function Get-TkeDatastoreFile {
param(
	[Parameter(Mandatory=$true,ValueFromPipeline=$true,HelpMessage="Datastores to get files from")]
	[VMware.VimAutomation.Client20.DatastoreImpl[]]
	$datastore,
 
	[Parameter(HelpMessage="Subpath to search")]
	[string]
	$subpath = "",
 
	[Parameter(HelpMessage="If set to true, don't get the file size")]
	[switch]
	$noSize,
 
	[Parameter(HelpMessage="If set to true, don't get the file type")]
	[switch]
	$noType,
 
	[Parameter(HelpMessage="If set to true, don't get the file modification date")]
	[switch]
	$noModification
)

This code defines one parameter set. The first parameter, $datastore, is mandatory and is also accepted on the pipeline. The type of $datastore is an array of VMware.VimAutomation.Client20.DatastoreImpl objects, which helps PowerShell know whether a given object on the pipeline should be accepted or not. The second argumetn sets a default value of the empty string. The last 3 arguments, noSize, noType and noModification are switch parameters. For example, if this function is called as Get-TkeDatastoreFile -noType, $noType will be set to $true while $noSize and $noModification will both be set to $false.

If you're ever unsure about the type of an object, you can always call its GetType() method to find out what it is, for example:

> $str = "fdsa"
> $str.GetType()
 
IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Begin, Process and End

Dealing with tasks

Supporting -Whatif and -Confirm

If you function changes system state it should support -Whatif and -Confirm. Examples include changing a system setting, creating a new object (like a VM) or removing an existing object. Adding -Whatif and -Confirm support is done with the CmdletBinding directive, for example:

[CmdletBinding(SupportsShouldProcess=$true,ConfirmImpact="high")]

If your function defines these, your function will have access to a variable called $psfunction that you can use to support -Whatif and -Confirm. All you need to do then is, before taking action that would change system state, make a call like this:

if (($psfunction.ShouldProcess($objectName, $message))) {
	// Change the system.
}

If the user has specified -Whatif, they will simply get a message showing them the object name and message. If -Confirm has been specified, and the functions ConfirmImpact setting is greater than or equal to than the user's $ConfirmPreference variable, they will be prompted to decide if the action should truly take place.

Documentation

Advanced functions can have documentation embedded in the module that is displayed when a user types help Your-AdvancedFunction.

For example, this code snippet defines help for the Defrobulate-Modulator cmdlet.

<#
.SYNOPSIS
Removes all frobulations from the system modulator.
.DESCRIPTION
Only use this command if you are a certified modulator technician.
.LINK
Frobulate-Modulator
#>
Function Defrobulate-Modulator {
	# Code withheld pending patent approval.
}

When the user types *help Defrobulate-Modulator at his prompt, the following is produced:

PS> help defrobulate-modulator
NAME
    Defrobulate-Modulator
 
SYNOPSIS
    Removes all frobulations from the system modulator.
 
 
SYNTAX
    Defrobulate-Modulator [<CommonParameters>]
 
 
DETAILED DESCRIPTION
    Only use this command if you are a certified modulator technician.
 
 
RELATED LINKS
    Frobulate-Modulator
 
REMARKS
    To see the examples, type: "get-help Defrobulate-Modulator -examples".
    For more information, type: "get-help Defrobulate-Modulator -detailed".
    For technical information, type: "get-help Defrobulate-Modulator -full".

Following is a list of all documentation sections.

Updated Wiki: examples

LucD — Wed, 31 Dec 2008 17:53:04 GMT

Roles, privileges and permissions
The security in virtual infrastructure (VI) is organised around

privileges, specific rights on ESX Servers, Virtual Machines, or other VI objects. For example the right to start a Virtual Machine
roles, are objects that group specific rights together for easier assignment. The Virtual Machine User role has several rights to intercat with a guest.
permissions, is where you combine users, or groups, with specific roles.

To see all the available privileges in VI you can do:

PS C:\> Get-TkeAllPriviliges
 
Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read
ManageCustomFields                                               False Global                             Global.ManageCustomFields

PS C:\> Get-TkeRoles
 
 
Name      : NoAccess
Label     : No Access
Summary   : Used for restricting granted access
RoleId    : -5
System    : True
Privilege :
 
Name      : Anonymous
Label     : Anonymous
Summary   : Not logged-in user (cannot be granted)
RoleId    : -4
System    : True
Privilege : {System.Anonymous}
 
Name      : View
Label     : View
Summary   : Visibility access (cannot be granted)
RoleId    : -3
System    : True
Privilege : {System.Anonymous, System.View}

PS C:\> Get-TkeRoles | where {$_.Name -eq "ReadOnly"} | select -ExpandProperty Privilege
System.Anonymous
System.Read
System.View

but there is a specific advanced function to do just that

PS C:\> Get-TkeRolePrivileges -name "readonly"
 
Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read

Note that the names of the roles do not always correspond literaly with the role names you see in the VI Client.

To create a new role with a specific set of privileges you can do

PS C:\> New-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.PowerOn","VirtualMachine.Interact.PowerOff"
110

The advanced function returns the roleId of the new role.

Note that the privilege Ids are case-sensitive !

If you want to make changes to the privileges assigned to a user-defined role (remember, the roles with the positive roleId numbers) you can do

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Suspend"

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Reset" -append:$true

You can also change the name of a user-defined role

PS C:\> Set-TkeRole -name "My new role" -newName "A new name for the role"

If a role becomes obsolete, you can remove it like this

PS C:\> Remove-TkeRole -name "A new name for the role"

As a failsafe this cmdlet has a switch, called -FailIfUsed, which prohibits the removal of the role if the role is used in a permission.
The default for this switch is -FailIfUsed:$true.

PS C:\> Remove-TkeRole -name "A new name for the role" -FailIfUsed:$false

PS C:\> $MyPermission = New-Object VMware.Vim.Permission
PS C:\> $MyPermission.principal = "Test\Guest"
PS C:\> $MyPermission.group = $false
PS C:\> $myPermission.propagate = $false
PS C:\> $MyPermission.RoleId = (Get-TkeRoles | Where-Object {$_.Name -eq "ReadOnly"} | % {$_.RoleId})
PS C:\> Get-VM PC2 | Set-TkePermissions -permission $myPermission
PS C:\> Get-VM PC2 | Get-TkePermissions
 
Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly

PS C:\> Get-VM PC2 | Get-TkePermissions -inherited:$true
 
 
Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly
 
Entity    : Datacenters
Group     : True
Principal : TEST\Domain Admins
Propagate : True
Role      : Admin

The removal of a permission is rather straight-forward.

PS C:\> Get-VM PC2 | Remove-TkePermissions -principal "Test\Guest"

Updated Wiki: Home

LucD — Wed, 31 Dec 2008 12:28:44 GMT

Project Description
The VI Toolkit for Windows Community Extensions is a PowerShell module designed to work with the VI Toolkit for Windows (http://vmware.com/go/powershell).

Project Goals
This project aims to help make managing VMware products with PowerShell easy and really powerful. Our current VI Toolkit for Windows contains 125 cmdlets that makes life a lot easier for people who manage VMware ESX and VMware VirtualCenter. With this project we plan to build on that by providing libraries of really useful stuff based on the ideas we see in our VMware Community as well as plenty of ideas of our own.

How To Contribute
We welcome your ideas and code contributions. Feel free to request features through the Discussions or Issue Tracker tab, or upload patches through the Source Code tab.

Guidelines For VI Toolkit Extensions Functions
For tips on how to write a PowerShell advanced function that can be included in the Extensions, see guidelines.

VI Toolkit Extensions examples
For examples on how some of the advanced functions can be used see examples.

Updated Wiki: Home

cartershanklin — Mon, 29 Dec 2008 23:34:57 GMT