4.1 Modifying Virtual Machine Images by Using the Image Tool

Caution:

Before using the Image Tool to view or modify the configuration or file system of a virtual machine, shut down the virtual machine.

Do not attempt to use the Image Tool to view or modify the configuration or file system of a running virtual machine.

To modify a virtual machine image by using the Image Tool, do one of the following:

Modify the virtual machine image configuration directly by using the --reconfigure option of the Image Tool.

For more information, see Section 4.1.1, "Reconfiguring Virtual Machine Images.")
Modify the services (such as sshd) that are enabled in the virtual machine configuration by using the --reconfigure-service option of the Image Tool.

For more information, see --reconfigure-service in Appendix A, "Image Tool Command-Line Option Reference.".
Modify the file system within a virtual machine image by using the --file option of the Image Tool.

For more information, see Section 4.1.2, "Modifying the File System Within a Virtual Machine Image by Using the Image Tool.")
Extract the source components of the virtual machine image by using the --disassemble option of the Image Tool, make the required changes, and assemble (create) the virtual machine image again.

For more information, see Section 4.1.3, "Disassembling and Re-Creating Virtual Machine Images."

4.1.1 Reconfiguring Virtual Machine Images

You can use the -r (--reconfigure) option of the Image Tool to modify the configuration settings of a virtual machine image directly, bypassing the configuration XML file.

Note:

At any point, you can extract an XML file reflecting the current configuration state of a virtual machine by using the -d option.

For detailed information about the -r option, its operations, and the configuration settings that you can modify by using the option, see -r (--reconfigure) in Appendix A, "Image Tool Command-Line Option Reference."

Examples

Caution:

Before using the -r option or any other Image Tool option that accesses the virtual machine image, you must shut down the virtual machine.

To change the name of the virtual machine to newname, run the following command:
```
java -jar jrockitve-imagetool.jar -r vm.cfg set vm-name newname
```
To add an NFS mount point named mynfs pointing to the /export/mynfs path on the nfs.myhost.com server with the user ID 501 and group ID 502, run the following command:
```
java -jar jrockitve-imagetool.jar -r vm.cfg add mount nfs /mynfs nfs.myhost.com /export/mynfs uid=501 gid=502
```
To add a DNS server (with the IP address 10.172.22.5, for example), run the following command:
```
java -jar jrockitve-imagetool.jar -r vm.cfg add network-dns-servers 10.172.22.5
```
Consider a virtual machine image that currently has three DNS servers defined. If you run the -r option with the get network-dns-servers operation, the results are displayed in the lookup order, as shown in the following example:
```
#1 172.22.23.24
#2 172.22.23.25
#3 172.22.23.26
```
If you want to remove the second entry in the DNS server table, run the following command:
```
java -jar jrockitve-imagetool.jar -r vm.cfg remove network-dns-servers 2
```
The get operation now yields the following results:
```
#1 172.22.23.24
#2 172.22.23.26
```

4.1.2 Modifying the File System Within a Virtual Machine Image by Using the Image Tool

You can use the -f (--file) option of the Image Tool to copy files to and from the file system of a virtual machine image, view directory listings, move and delete files, create and delete directories, find files, and display the contents of text files.

Do not attempt to modify the file system of a virtual machine image unless you understand the file system. For more information, see Section 2.4, "About the File System of a Virtual Machine."

To modify the file system of a virtual machine image by using the Image Tool, shut down the virtual machine, and then run the following command:

java -jar jrockitve-imagetool.jar -f vm_cfg operation [parameters]

In this command, vm_cfg is the path and name of the configuration file (vm.cfg) corresponding to the virtual machine to be modified, operation is name of the modification task, and parameters represents the arguments that are required for the specified modification task.

Examples

Note:

For detailed information about the -f option, the operations it supports, the arguments it requires, and more examples, see -f (--file) in Appendix A, "Image Tool Command-Line Option Reference."

To copy the contents of the /jrockitve/log/jrockitve.log file in a virtual machine image to the /tmp/jrve.log file in the local file system, run the following command:
```
java -jar jrockitve-imagetool.jar -f vm.cfg get /jrockitve/log/jrockitve.log /tmp/jrve.log
```
To copy a Java class file named app.class from the /app/version2/ directory of the local system to the /vmapp directory of the virtual machine, run the following command:
```
java -jar jrockitve-imagetool.jar -f vm.cfg put /app/version2/app.class /vmapp
```

4.1.3 Disassembling and Re-Creating Virtual Machine Images

You can use the -d (--disassemble) option of the Image Tool to disassemble a virtual machine image into its individual components.

After disassembling a virtual machine image, you can modify the source Java application or change the configuration settings defined in the configuration XML file, and then create a new virtual machine image.

Note:

The -d option is especially useful when you want to modify virtual machines that have been in production for a while during which several changes might have been made, and you now want to examine and modify the current configuration or the Java application.

To disassemble a virtual machine image, shut down the virtual machine, and then run the following command:

java -jar jrockitve-imagetool.jar -d vm_cfg output_directory

In this command, vm_cfg is the path and name of the configuration file of the virtual machine (vm.cfg) and output_directory is the directory to which you want the disassembled components of the virtual machine image to be copied.

For more information, see -d (--disassemble) in Appendix B, "Configuration File Element Reference."