InventorySnapshot

Thank you for trying out our "InventorySnapshot" fling!

I. DESCRIPTION InventorySnapshot allows a user to "snapshot" a given vCenter inventory configuration and then

reproduce it.

To learn how to run InventorySnapshot, please go to section IV. To learn more about the fling, read

on

The "inventory" includes the Datacenter folders, datacenters, clusters, resource pools, vApps, hierarchy,

roles and permissions, configuration settings, and custom fields. In other words, if you have an inventory

with a given set of hosts and VMs organized into a group of clusters, we can faithfully reproduce this

environment, including the cluster settings and custom roles you may have defined.

As a simple example, suppose you have an inventory with one datacenter (DC A), one cluster (Cluster A),

and two hosts (Host A and Host B). At a high level, our fling emits a PowerCLI script that, when executed,

does the following:

1. Create Datacenter DC A.

2. Create cluster Cluster A.

3. Add host Host A to Cluster A.

4. Add host Host B to Cluster A.

Notice that this can be helpful for a variety of reasons. For example, suppose youve spent a lot of time

creating a development vCenter environment, and now you wish to deploy it in production. Using our

fling, you can snapshot your dev environment and then run it against the production vCenter server,

saving you the task of laboriously adding each host, creating the proper clusters and resource pools, etc.

II. PREREQUISITES AND ASSUMPTIONS

A. Java 1.6.0_23 or higher To run InventorySnapshot, you must have Java installed. We require version 1.6.0_23 or higher, and you

can use either the JRE or the JDK. If Java is not already installed on your system, please visit

http://www.oracle.com/technetwork/java/javase/downloads/index.html and download Java SE 6

Update 23.

B. PowerCLI 4.1.U1 or higher To run InventorySnapshot, you must have the VMware PowerCLI installed. In our case, we have tested

with version 4.1U1, build 332441. To download this, please see the following URL:

http://www.vmware.com/support/developer/PowerCLI. Note that to complete this step, you will also

need to install Powershell, as discussed in the PowerCLI documentation.

C. Assumptions We make the following assumptions about an inventory:

1. VMs are already registered on their hosts. 2. Entity names (VMs, Folders, etc.) are unique within an inventory.

III. BASIC OVERVIEW This vCenter fling takes a snapshot of the vCenter inventory and creates a bunch of binary files to

describe this inventory and the configuration of the various entities (clusters, networks, etc.). More

importantly, it also creates a file called "createInventory.ps1." This is a PowerCLI script.

This PowerCLI script contains commands to re-create the inventory that you've just archived. Feel free

to take a look! It is important to note that re-creating most inventories requires adding hosts. As a

placeholder for the actual passwords of the hosts being added, our script generates -password

'PASSWORD' in the createInventory.ps1 script. Using the UI, we enable you to change the passwords

for each host. Of course, you can also open up the file in the editor of your choice and change them

yourself. Please note that for now, we store the PowerCLI script as a plaintext file, so your passwords are

cleartext. If there is sufficient demand, we can work on changing this.

Therefore, using our fling in the most basic way is a three-step process:

a. Snapshot the inventory using the UI.

a. In Windows, double-click on inventorySnapshot.bat to bring up the UI.

b. In Linux and MacOS, use the inventorySnapshot.sh shell script to bring up the UI.

b. Edit the createInventory.ps1 PowerCLI script so that the host passwords are correct. You can

do this using the UI, or you can manually edit the createInventory.ps1 file using your

favorite text editor. Just search for 'PASSWORD' to see where you need to input the proper

passwords. If you use the UI, the file is saved as createInventory-PasswordModified.ps1.

c. Login to a vCenter server using the PowerCLI, change into the directory that contains the

createInventory.ps1 script, and just type .\createInventory-PasswordModified.ps1. If you

edited the script by hand and saved it as createInventory.ps1, then type

createInventory.ps1 instead.

IV. STEP-BY-STEP GUIDE TO USING THIS FLING 1. We assume you are running this on Windows. For Linux or MacOS users, the steps are almost

exactly the same, except you will use inventorySnapshot.sh instead of inventorySnapshot.bat, and

you will have to copy the generated PowerCLI files to a Windows host to run them.

2. Download the zip file from the web site. Let's call this "inventorysnapshot.zip."

3. When you unzip this file, you'll see a directory called inventorysnapshot. We will assume that you

have downloaded this in C:\, so that the full path is C:\inventorysnapshot\.

4. If you go into this directory, you will see a file called inventorySnapshot.bat. Double-click on this file

(or just run it from the command-line) and a UI will appear (see Figure 1).

Figure 1: Login screen for InventorySnapshot UI. Use "inventorySnapshot.bat" (or inventorySnapshot.sh in Linux/MacOS) to get this screen.

5. In the UI, there are 4 text fields:

a. vCenter Server Name. This is the vCenter server whose inventory you would like to

snapshot.

b. vCenter username. This is the administrator user for vCenter server. Please note that you

must have administrator access in order to run InventorySnapshot.

c. vCenter password. The password for the administrator user.

d. Directory for storing snapshot data. This is the destination directory where

InventorySnapshot should write its output.

6. Once you have filled in these 4 fields, click on the Take Snapshot button. After some time

(depending on the size of the inventory), a new screen will appear, as seen in Figure 2.

Figure 2: InventorySnapshot output. After InventorySnapshot has snapshotted an inventory, this tabbed view appears. The tabbed view contains the generated PowerCLI code and tabs for changing passwords and selecting portions of inventory to restore.

7. This tabbed view has 4 screens. The default screen (PowerCLI Code) shows the PowerCLI code that

was generated by the InventorySnapshot application after clicking Take Snapshot from the login

screen. This screen is not editable, but you can scroll through it to take a look at the code that has

been generated to recreate your inventory. This code is also written to a file called

createInventory.ps1 in the destination directory that you specified in step 5.

8. If you click on the Host Information tab at the top of the screen, you will see a new screen that will

let you edit the passwords in the PowerCLI file and save this edited PowerCLI into a new file. The

Host Information tab is shown in Figure 3.

Figure 3: The Host Information tab. This view allows the user to edit generated PowerCLI file so that it has the proper host passwords.

9. You can edit the passwords on this screen in several ways:

a. The Hostname, Username, Password table can be edited. Simply click in the Username

field to change the username for a host, and click in the Password field to edit the password

for that host. After you are done editing each host, click on the Commit changes button.

(In the screenshot above, the Commit changes button is slightly truncated to be Commit

chan Sorry!). If you resize the entire window slightly, this should go away. Also, if the text

fields do not appear, then click on a different tab (like the Inventory Tree tab) and then

click back to the Host Information tab.

b. If you have the same username/password combination for every host, you can fill in that

hostname and password combination in the text fields labeled username and password

underneath the label Apply same username/password to all hosts. After you have filled in

those two text fields, again click on Commit changes.

c. For one more slightly complicated example, suppose all hosts but one have the same

username and password. You can fill in the username/password under Apply same

username/password to all hosts and click on Commit changes, and then you can edit the

table for the host that has a different username/password and then click on Commit

changes again.

10. After editing the passwords and clicking Commit changes, a dialog box shows up to indicate that a

file named createInventory-PasswordModified.ps1 has been created in the destination directory

that you specified.

11. Next, you can click on the Inventory Tree tab to see an overview of your inventory. This overview

will be similar to the view you can see in the UI client, but it may have some extra elements (like

default host folders) that are typically hidden in the VI client, as you can see in Figure 4.

Figure 4: Inventory Tree View. The Inventory Tree shows you the inventory of the vCenter that you have just snapshotted, including some extra folders that are typically hidden in the VI client.

12. By default, when you clicked on Commit changes in the Host Information tab, our

InventorySnapshot UI created a PowerCLI file named createInventory-PasswordModified.ps1. This

file allows you to recreate an entire inventory. If you would like a script that recreates an individual

datacenter, you can do this from the Inventory Tree view. To do this, click on the datacenter in the

Inventory Tree view, make sure all elements beneath it are selected (this is typically accomplished

by minimizing the datacenter and then clicking on its checkbox), and then click on Commit

changes at the bottom of the screen. A screenshot of the UI when a given datacenter (in this case,

AppCloud) has been clicked is shown in Figure 5.

Figure 5: Inventory Tree View with a specific datacenter selected. After selecting a datacenter and clicking on "Commit changes", you can go to the "Generate New PowerCLI Code" tab to create a file to reproduce this datacenter.

13. Once you have clicked on Commit changes, a confirmation dialog box comes up. This box tells you

all of the datacenters that you have selected as well as all of the clusters underneath those

datacenters. In this case, the AppCloud datacenter was selected, and it has one cluster inside

called AppCloudCluster. See Figure 6.

Figure 6: Dialog box showing selected datacenter and the clusters it contains. When you go to the "Generate New PowerCLI Code" tab and hit "Generate PowerCLI Code", PowerCLI files for this datacenter and its cluster will be created.

14. Next, please click on the Generate New PowerCLI Code tab, shown in Figure 7.

Figure 7: Generate New PowerCLI Code tab. When you click on the "Generate PowerCLI code" button, PowerCLI files for restoring the inventory and the datacenters you've selected will be generated.

15. On the Generate New PowerCLI Code tab, click on the Generate PowerCLI code button. For our

example, since we selected a datacenter, and that datacenter has 1 cluster, we will see 3 dialog

boxes.

a. createInventory-PasswordModified.ps1: a PowerCLI script to reproduce the entire

inventory.

b. createInventory-ClusterComputeResource-AppCloudCluster.ps1: a PowerCLI script to

reproduce cluster AppCloudCluster by itself.

c. createInventory-Datacenter-AppCloud.ps1: a PowerCLI script to reproduce the datacenter

AppCloud by itself.

16. You can now take these PowerCLI files, connect to the same or to a different vCenter server using

the PowerCLI, and then execute these scripts.

a. If you want to reproduce the entire inventory, use createInventory-PasswordModified.ps1.

b. If you want to reproduce just a single datacenter, use createInventory-Datacenter-

AppCloud.ps1 (assuming the datacenter is named AppCloud).

c. If you want to reproduce just a single cluster, use createInventory-

ClusterComputeResource-AppCloudCluster.ps1 (assuming the cluster is named

AppCloudCluster).

Important note: the InventorySnapshot UI runs on Linux, MacOS, and Windows, but PowerCLI only

runs on Windows. So if you run InventorySnapshot on Linux or MacOS, you will have to copy the

generated PowerCLI files to a Windows host in order to run them.

To run the script, follow these steps:

a. Start up the PowerCLI, connect to the vCenter server that youd like to archive (connect-

viserver , and change directory (cd) into the directory with the inventory snapshot

PowerCLI files. In the next 3 steps (b, c, and d), we assume you want to create this inventory on an

entirely new vCenter server named vcenter.mydomain.com and that youve saved the PowerCLI

files in the directory called C:\tmp\10.115.147.115-733pm.

b. [vSphere PowerCLI ]> connect-viserver vcenter.mydomain.com.

()

c. [vSphere PowerCLI]> cd C:\tmp\10.115.147.115-733pm\

d. [vSphere PowerCLI]> createInventory-PasswordModified.ps1

17. To exit the UI, click on the X at the top right of the screen. Sorry, we havent added a menu-driven

interface for exiting yet.

V. FOR THE CURIOUS: MORE DETAILS ABOUT THIS FLING

At present, we generate PowerCLI code in order to reproduce an inventory. As a result, this generated

code can only be run on Windows. However, to generate the PowerCLI code, you can use Linux,

Windows, or MacOS. If you look at the generated code before youve used the UI to modify the

passwords (lets say createInventory.ps1), the file looks something like this: # ### START RESTORE DC: Empty DC 3

# ### START CREATE DC: Empty DC 3

# Create DC: Empty DC 3 in folder: null

$folder = Get-Folder -NoRecursion

New-Datacenter -Location $folder -name "Empty DC 3"

# ### END CREATE DC: Empty DC 3

# ### START CREATE FOLDER: DC Folder 1

# Create Datacenter Folder DC Folder 1

$parentFolder = Get-Folder -NoRecursion

New-Folder -name "DC Folder 1" -Location $parentFolder

1. The lines that begin with # ### START or # ### END are called markers. We use these

comments to help you understand what the code is doing. For example, the above snippet is

creating a datacenter named Empty DC 3 and creating a datacenter folder named DC Folder

1.

2. In recreating an inventory, you will invariably have to add hosts. You will see lines like these in

the createInventory.ps1 script: Add-VMHost 10.115.144.34 -Location $cluster -user root -password

'PASSWORD' -Force

Using the UI, you can edit the passwords for each host accordingly. This creates a file called

createInventory-PasswordModified.ps1. Alternatively, you can edit this file by hand to replace

PASSWORD with the appropriate password for that host. You will have to do this for each host

in the file.

VI. POSSIBLE USE CASES

A. Restoring an entire inventory to the same vCenter server Suppose you have a vCenter server and you want to start fresh by blowing away its inventory (using

vpxd b) and then restoring the inventory.

1. First, take a backup of your database in case something goes wrong.

2. Second, follow the steps in Section IV to snapshot the inventory of the vCenter server.

3. Clean out the inventory (perhaps you remove the inventory from the root or use vpxd b).

4. Next, connect a PowerCLI shell to the vCenter server. Its inventory should now be empty.

5. Run the script generated in step 2 (it is probably called createInventory-PasswordModified.ps1).

in this PowerCLI shell.

B. Restoring an entire inventory to a different vCenter server If you want to take the inventory on vCenter A and restore it on vCenter B,

1. First, follow the steps in Section IV to snapshot the inventory on vCenter A.

2. Next, connect a PowerCLI shell to the destination vCenter server (vCenter B).

3. Run the PowerCLI script generated in step 1 in the PowerCLI shell that is connected to the

destination vCenter server.

C. Restore roles & permissions to a different vCenter server Another use case is simply archiving roles and permissions. Suppose you have vCenter server A and it has some custom roles and permissions, and you would like to replicate those on vCenter server B. This might be useful if you are creating a new vCenter server and are not using Linked Mode to synchronize roles. One way to archive and restore roles is to perform the steps in Section IV above and then examine the generated PowerCLI code (which probably resides in createInventory-PasswordModified.ps1). You should look for the following in the PowerCLI file: # ### START UPDATE ROLE_PERM: ALL

# Fixing up Roles and Permissions

# Compare archived roles to current roles and add new ones if necessary

$roleNameList = Get-VIRole | sort-object name | select name

# Get Authorization Manager

$_this = Get-View -Id AuthorizationManager-AuthorizationManager

# Set permissions

$_this.SetEntityPermissions($entityMoRef,$permission)

# ### END UPDATE ROLE_PERM: ALL

The code between the markers ### START UPDATE ROLE_PERM: ALL and ### END UPDATE

ROLE_PERM: ALL restores permissions and roles. In theory, if you just copied this code to a separate

PowerCLI file and then ran it on the destination server, you could reproduce roles and permissions on

the destination. However, there are some important caveats:

1. You must have the same users and groups (from Windows) installed on the destination server

before you run this PowerCLI code. If restoration of roles and permission does not work, please

make sure that the users and groups on the source vCenter server are present on the

destination vCenter server.

2. The code that weve generated is extremely slow and very general. For example, it tries to

restore all permissions (including the standard permissions that are included in every vCenter

installation). This may result in some benign errors in which our PowerCLI code tries to restore

roles that already exist. If you see errors like the following when you run the script, it is likely

due to this issue, and these errors can be safely ignored:

Exception calling "SetEntityPermissions" with "2" argument(s): "The requested

change cannot be completed because it could leave the system without full

administrative privileges for a user or group."

At C:\tmp\10.115.147.115-656pm\createInventory-Datacenter-AppCloud.ps1:1187

char:28

+ $_this.SetEntityPermissions

Add-VMHost : 4/30/2011 10:40:04 PM Add-VMHost This host is already being

managed by this vSphere server.

At C:\tmp\vCenterA\createInventory-ClusterComputeResource-haCluster.ps1:13 char:11

+ Add-VMHost

At C:\tmp\vCenterA\createInventory-PasswordModified.ps1:1463 char:26

+ $cfView.AddCustomFieldDef

B. ALARMS NOT YET SUPPORTED Currently, we do not record the alarms registered with vCenter, so we can't reproduce them. Instead, if

you are using non-default alarms or alarm actions, you will have to re-create them on the new vCenter

server. We are working hard on this case so stay tuned!

C. SPECIAL CHARACTERS Please avoid special characters (except -, which is fine) in the names of your VMs, etc. This may cause

the script not to work properly. Also, if you have # in your passwords, the PowerCLI scripts might have

unpredictable behavior.

D. DOES NOT SUPPORT VAPPS ON STANDALONE HOSTS If you have vApps on standalone hosts, our script will fail. We do support vApps that are defined within

clusters, however.

E. REQUIRES USERS OR GROUPS TO EXIST IN ORDER TO RESTORE ROLES If you have a custom role defined for a user or group, please make sure the user or group exists on the

destination vSphere server before you try to restore the role.

F. MAY NOT SUPPORT NON-ENGLISH CHARACTERS We do not yet support custom languages other than English. If you need support for other languages, let

us know. The main issue is making sure that characters like umlauts are properly supported, and our lack

of support is simply due to lack of testing on other languages. If you test our code and find bugs, let us

know and well try to address them.

G. MANAGED OBJECT IDs ARE CHANGED When you restore an inventory, all of the entity IDs (for example, a host might be host-1123, or a VM

might be vm-1245) will be different from the archived version. We hope this is not a big limitation, since

this is the same behavior that youd experience if you removed a host from one vCenter server and

added it to a different one.

H. SUPPORTS VC4.0 TO VC4.0 or above InventorySnapshot can be used to snapshot a VC4.0 environment and then restore it to a vCenter server

running version 4.0 or above (e.g., 4.0 or 4.1).

I. BUG: MOVING VAPPS INTO FOLDERS SOMETIMES FAILS When restoring a cluster by itself (as opposed to restoring a datacenter), vApps will not be moved

properly into their parent folders, if the parent folder is a non-root folder. This is a known bug and will

be fixed in a future release.

J. ONLY SUPPORTS VMWARE DVS Currently, we do not support vendor-specific DVS switches (like Cisco Nexus 1000V). We can add such

support if there is enough demand.

K. UNRELATED DATACENTER FOLDERS GET CREATED Suppose I wish to restore just datacenter A, and in the same inventory hierarchy there is an unrelated

datacenter folder B. When restoring datacenter A to a vCenter server, our code may create an empty

datacenter folder named B even though we dont add any of the hosts, clusters, or datacenters under

Folder B. This is a known bug in our code and we hope to address this in the next release.

VIII. Basic troubleshooting 1. The UI does not start up.

a. Please make sure that the proper version of Java (JRE 1.6.0_23) is installed.

2. I see errors in the PowerCLI output, but my inventory looks correct. Should I be scared?

a. Our code generates some benign PowerCLI errors. Please check the various case studies

in section VI to see if your errors are described there. If not, you might wish to notify us

so we can take a look. In summary, you may see some benign errors when restoring

roles and permissions, when restoring custom fields, and when restoring resource pools.

3. My inventory didnt restore properly

a. When running the PowerCLI code, please make sure you are logged in as the

Administrator user (or rather, a user that has complete access to the vCenter inventory).

b. If the Hosts and Clusters view in the VI client shows that your inventory isnt the same

as what you snapshotted, please inspect the PowerCLI code to make sure that all host

passwords are correct. Also, please make sure that the names of various objects (like

hosts, VMs, folders, and resource pools) are unique within your inventory.

c. If you tried to restore a cluster and it didnt work, please make sure its parent

datacenter exists on the destination server. Look in the section entitled Restoring DRS

cluster settings for more information.

d. If your folder view (Host folder or VM & Templates Folders) is incorrect, please make

sure you arent encountering a known bug (section CAVEATS/KNOWN BUGS above). If

none of these works, it may be a new bug and you should post a message to the flings

web site or contact us.

e. Please make sure the PowerCLI is connected to the appropriate destination vCenter

server. If you keep a PowerCLI shell open too long, it automatically disconnects from

vCenter, so you may have to reissue the connect-viserver command.

f. Please make sure the PowerCLI is only connected to one vCenter server (as opposed to

multiple vCenter servers).

4. Restoring an inventory takes a long time.

a. We have tried to focus on correctness in this version of the fling. We hope to improve it

in upcoming releases.

5. My Roles and Permissions arent restored properly.

a. See the section entitled Restore roles & permissions to a different vCenter server

above.

6. My cluster settings arent restored properly.

a. Please see the section entitled Restoring DRS cluster settings first. If this section does

not explain the problem, it might be a bug in our code.