Table of Contents
General description
CHARON-AXP provides the following set of utilities:
| Utility | Description |
|---|---|
| mkdskcmd | Used to create CHARON virtual disk containers of custom or standard types. This utility also may be used to transfer virtual disks of one type to virtual disks of another type. |
| hasp_srm_view | Used to display the CHARON license contents, to collect the host system fingerprint and to transfer software licenses from one host to another. |
| hasp_update | Sentinel standard utility used to retrieve Sentinel protection key information, detach a license from a Sentinel SL key and rehost a license from a Sentinel SL key |
| ncu | Used to dedicate a host interface to CHARON-AXP, to release it back to the host and to manage CHARON virtual interfaces (TAPs). |
| mtd | Used to create CHARON tape images from physical tapes and to write tape images back to physical tapes. |
| CHARON Guest Utilities for OpenVMS | Used to manage virtual tapes and CHARON performance. |
All these utilities are invoked from Linux console command line.
'mkdskcmd' utility
Creating disk images
The "mkdskcmd" utility:
- Creates empty disk images of a given standard disk type or a custom disk size
- Transfers existing disk images of one type to disk images of another type.
The first step is to obtain the name of the disk that needs to be created:
$ mkdskcmd --list |
This command results in a list of all supported disk types.
Choose the desired disk (for example "RZ22"), then use the "mkdskcmd" command to create the virtual disk image as shown below:
$ mkdskcmd --disk rz22 --output rz22.vdisk |
A disk container "rz22.vdisk" will be created in the current directory.
A file "rz22.avdisk" will also be created. This file helps CHARON accurately recognize a specific disk image type. It is recommended to put the ".avdisk" file in the same directory as the created disk image.
It is also possible to create custom disk images using "--blcount" (blocks count) and "--blsize" (blocks size) switches.
To get all the available parameters please use the "–help"switch:
|
The "--avtable" parameter is used to work with an alternative disk specification database (or to point to the standard database ("mkdsk.vtable") if it is in a location other than the current directory).
The "--blcount" (blocks count) and "--blsize" (blocks size) switches are used to create custom disk images.
Transferring disk images
The "mkdskcmd" utility is able to transfer (copy) disk images of one type to a disk image of another type.
This operation is needed, for example, to obtain more free space on a disk image that already contains data.
Note: it is not possible to add more free space dynamically. CHARON-AXP must be stopped before performing this operation.
If a source disk image is larger than the target disk image, the extra data is lost. If the source disk image is smaller, it will be extended and padded with null bytes ('\0').
An example of the syntax follows:
$ mkdskcmd --transfer <source disk file name> <source disk parameters> [--shrink] [-k] |
where:
<source disk file name> - a file name of the disk image to be transferred
<source disk parameters> - the name of the disk from the list provided by the "mkdskcmd --list" command execution or the disk geometry specification (see below).
- --shrink or -k - used in the case where the target disk is transferred to a smaller disk.
Example:
$ mkdskcmd --transfer /etc/rz22.vdisk rz25 |
It is also possible to specify the disk parameters manually with "--blcount / -c" (blocks count) and "--blsize / -z" (blocks size) switches:
$ mkdskcmd --transfer <source disk file name> -blsize <number> -blcount <number> |
Example:
$ mkdskcmd -t /etc/custom.vdisk -z 512 -c 262134 |
There is a certain delay between the moment when the utility reports that a disk image has been transferred and its actual availability to CHARON. This delay can reach to several minutes in case of very big disks transfers. It happens because the host operating systems needs some time for actual allocation of the enlarged file on HDD.
'mtd' utility
The "mtd" utility is used to:
- Create a CHARON tape image from a physical tape
- Write a tape image to a physical tape.
Usage is the following:
$ mtd [options] <tape device name> <tape container name> |
where the options are:
| Parameter | Description |
|---|---|
-l <file name> | Creates an execution log “file name”. |
-r <number> | Specifies a number of attempts to read a damaged data bock |
-i | Directs to ignore bad blocks and continue processing without interruption. It implies "-r 0" |
-n | Do not rewind tape |
-p | Disable progress reporting |
-v | Enable verbose trace of data transfer (implies "-p") |
Example:
$ mtd -l tape1.txt -r 10 /dev/st5 /charon/tapes/tape1.vtape |
Use the following syntax to write the content of a tape container to a physical tape:
$ mtd <tape container name> <tape device name> |
Example:
$ mtd /charon/tapes/tape1.vtape /dev/st5 |
'hasp_srm_view' utility
The "hasp_srm_view" utility displays content of CHARON-AXP licenses.
Run the utility with one of the following parameters to see the license(-s) details:
- "-l" (or without parameters) - CHARON default license details
- "-all" - all available CHARON licenses details
- "-key <key number>" - specific CHARON license (defined by its "key number") details
The "hasp_srm_view" utility provides the following functionality:
- Display the CHARON-AXP licenses details. It is possible to view all available license or some specific one.
- Collecting license status information
- Collecting host fingerprint information
Run the utility without any options to display the license details.
|
The specific type of CHARON license defines what switches may be used in each case.
Collecting the "c2v" file can be done only from the CHARON host console.
Remote collection of status information
For remote collection of status information it is recommended to use "ssh" as shown in the following examples:
# ssh root@CHARON_HOST /opt/charon/bin/hasp_srm_view -c2v /opt/charon/bin/my_hasp_key.c2v# ssh root@CHARON_HOST /opt/charon/bin/hasp_srm_view -fgp /opt/charon/bin/my_host_fingerprint.c2v |
To see the license text on the console:
# ssh root@localhost /opt/charon/bin/hasp_srm_view |
To collect license text to an output file on host server:
# ssh root@localhost /opt/charon/bin/hasp_srm_view > /opt/charon/bin/hasp_srm_view.txt |
The "hasp_srm_view" utility always reports the ID and IP address of the host(s) where active licenses are found.
'hasp_update' utility
The "hasp_update" is a Sentinel standard utility for license management included in CHARON-AXP kit.
To invoke the "hasp_update" utility login as "root" and use the following syntax:
# hasp_update <option> [filename] |
where:
| Parameter | Value | Description |
|---|---|---|
| <option> | u | Updates a Sentinel protection key / attaches a detached license |
| i | Retrieves Sentinel protection key information | |
| d | Detaches a license from a Sentinel Software License (SL) key | |
| r | Rehost a license from a Sentinel Software License (SL) key | |
| h | Display help | |
| [filename] | Path to the V2C/H2R file when used with the 'u' option | |
Optional path to the C2V file when used with the 'i' option Uses "stdout" if file name is not specified | ||
Example:
|
We recommend to use this tool only for "Update a Sentinel protection key / attach a detached license" function ("u" option). For the rest use "hasp_srm_view" utility.
'ncu' utility
The "ncu" ("Network Control Utility") is used to dedicate a host interface to CHARON-AXP, to release it back to the host and to manage CHARON virtual interfaces (TAPs).
The utility allocates chosen network interfaces (both physical and virtual) and configures the offload parameters.
Dedication of a host physical interface to CHARON
Login as root and enter "ncu". The following menu will appear:
=================================================================
1 - Dedicate to CHARON
|
The utility lists available network interfaces (both physical and virtual) and indicates whether they are dedicated to the host or to CHARON and whether they are currently in use by host operating system.
"ncu" offers several options:
- Dedicate interface to CHARON
- Release interface to host
- Create a bridge between a chosen physical network interface and the Linux virtual network and create a number of virtual network interfaces
- Remove the Linux virtual network and all the created virtual network interfaces
- Add VLAN interface
- Remove VLAN interface
- Print status - use it to display status of network interfaces and the menu shown above
- Exit
In the example above we see 2 network interfaces - "eth0" and "eth1", both of them are dedicated to host, but host uses only the interface "eth0".
Let's dedicate the interface "eth1" to CHARON-AXP.
Enter "1", then type "eth1" and press Enter:
1 - Dedicate to CHARON
|
Now the interface "eth1" is dedicated to CHARON-AXP:
=================================================================
1 - Dedicate to CHARON |
Enter "8" to return to console prompt.
Now "eth1" can be used by CHARON-AXP.
Release of a host physical interface back to host
Login as root and enter "ncu". The following menu will appear:
=================================================================
1 - Dedicate to CHARON
|
Let's say that we want to return the interface "eth1" (currently dedicated to CHARON) back to host. To do that enter "2" then "eth1":
1 - Dedicate to CHARON
|
Enter "8" to quit the "ncu" utility.
The interface "eth1" is released back to host system now.
Creation of a virtual network
Login as root and enter "ncu":
=================================================================
1 - Dedicate to CHARON
|
Enter "3" to create a bridge between the host physical network adapter and the LINUX virtual network interfaces (TAP) and specify the physical network interface ("eth1" in our example) and the number of virtual network interfaces to be created (2 in our example):
1 - Dedicate to CHARON
|
Now enter "7" to see the created virtual interfaces:
eth0 host connected to host
1 - Dedicate to CHARON
|
In the example above we see 2 virtual network Interfaces "tap0" and "tap1" connected to the created bridge. The physical network interface "eth1" is used for the bridge to the virtual network interfaces.
The interfaces "tap0" and "tap1" are ready to be used in CHARON configurations - they do not need to be additionally dedicated to CHARON.
Enter "8" to quit "ncu" utility.
Removal of a virtual network
Login a root. Start "ncu" utility:
eth0 host connected to host
1 - Dedicate to CHARON
|
Enter "4" then enter the interface name that is a bridge to the Linux virtual network on this host ("eth1" in our example):
1 - Dedicate to CHARON
|
Enter "8" to quit "ncu" utility.
Adding VLAN interface
Login a root. Start "ncu" utility:
=================================================================
1 - Dedicate to CHARON
|
Enter "5" then enter:
- The phisical interface name to be used for creating VLAN
- The ID of the VLAN device
- IP address of the VLAN device. Skip this step if no IP is required
- Network mask of the VLAN device. Enter for no network mask.
Specify the phys interface used for VLAN:eth1
1 - Dedicate to CHARON
|
Enter "8" to quit "ncu" utility.
Removing VLAN interface
Login a root. Start "ncu" utility:
================================================================= ========================== VLAN =================================
1 - Dedicate to CHARON
|
Enter "6" then enter the VLAN interface for remove:
| Specify the VLAN interface, which be removed: eth1.111 Removed VLAN -:eth1.111:-
1 - Dedicate to CHARON
|
Enter "8" to quit "ncu" utility.
CHARON Guest Utilities for OpenVMS
The "CHARON Guest Utilities for OpenVMS" (CHARONCP) package contains several utilities for managing virtual tapes, changing the emulator speed and creating useful definitions for that operations.
This set of utilities is located in the "charoncp011.vdisk" disk file in the "/opt/charon/disks".
Installation
Specify this image in the CHARON configuration file, boot from the system disk and mount the disk with the following OpenVMS command:
$ MOUNT <device name> /OVERRIDE=IDENTIFICATION |
Issue the following commands to install the package:
|
Select all the components included to the package:
|
Proceed with installation using all the default options.
Once the installation is completed, update "SYSTARTUP_VMS.COM" file with the following line:
$ @SYS$STARTUP:CHARONCP_STARTUP |
After that the package will be loaded automatically on startup.
Performance optimization
CHARON takes 100% of host CPU even in case of idle state of guest OpenVMS operating system. To get rid of such resources consumption there is a specific option provided by CHARON Guest Utilities - "idle" mode.
| Command | Description |
|---|---|
| $ CHARONCP SET IDLE /ENABLE | Loads the OpenVMS idle loop detection software. This allows CHARON to detect when the emulated CPU(s) are idle and use the host power saving instructions to reduce power usage. |
| $ CHARONCP SET IDLE /DISABLE | Unloads the OpenVMS idle loop detection software. |
Virtual tapes management
Specify mapping to tape container in the following way in the CHARON configuration file:
set <adapter name> container[<unit name>] = ".vtape" removable[<unit name>] = true |
Example:
set PKA container[600] = ".vtape" removable[600] = true |
Once it is done using the following commands it is possible to manage virtual tapes attached to CHARON:
| Command | Description | |
|---|---|---|
| $ CHARONCP SET MAGTAPE <device> /LOAD="<filename>.vtape" | Create the specified host-file (if it does not already exist) and attach it to the specified virtual tape device. Example:
| |
| $ CHARONCP SET MAGTAPE <device> /UNLOAD | Detach any file currently attached to te specified virtual tape device. Example:
|
Possible errors:
| Error | Description |
|---|---|
| BADFILENAME | The filename specified as a value to the qualifier /LOAD was either too long or does not have a file extension of ".vtape". |
| DEVNOTDISM | Attempting to execute a SET MAGTAPE/LOAD when a file is already attached. Perform a SET MAGTAPE/UNLOAD first. If a SET MAGTAPE/LOAD command has not previously been executed, then the CHARON configuration container specification for the tape device may contain a full path. Doing this will create and attach and initial tape container file. To avoid this, remove the file name from the specification (leaving only a fileextension of ".vtape" and optional directory). |
If some tape container has been already specified in the CHARON configuratioon file use the command "CHARONCP SET MAGTAPE <device> /UNLOAD" to unload it first.
Defining keys
It is possible to define certain keys on the terminal keyboard for fast access to the CHARONCP functionalilty while you are in CHARONCP:
| Command | Description | |
|---|---|---|
$ CHARONCP | Defines an equivalence string and a set of attributes with a key on the terminal keyboard. You can have a set of keys defined automatically for use with the CHARONCP utility by placing DEFINE/KEY commands in the file SYS$LOGIN:CHARONCP_KEYDEFS.INI Example:
| |
| $ CHARONCP CHARONCP> SHOW KEY <key-name> | Displays key definitions created with the DEFINE/KEY command. Refer to the DCL help entry for SHOW KEY for further information. Example:
|
For more information refer to the OpenVMS DCL Dictionary (DEFINE/KEY section).
Displaying version
| Command | Description | |
|---|---|---|
| $ CHARONCP SHOW VERSION | Displays the CHARONCP package version number and architecture. This can be useful for customers reporting issues with the CHARONCP software. Example:
|