Registering the Policy Agent from the Windows Command Line

Before You Begin 

Make sure that you know:

  • The IP addresses of all KeyControl nodes with which you want to register the Policy Agent. Registering the Policy Agent with multiple KeyControl nodes provides a failover mechanism in case one of the KeyControl nodes is unreachable.

  • The login credentials for a KeyControl webGUI account with Cloud Admin privileges.
  • The name of the KeyControl Cloud VM Set with which you want to associate the VM. You cannot encrypt the drive until it has been associated with a Cloud VM Set in KeyControl. For details, see Creating a Cloud VM Set.

Procedure 

  1. When you register the VM, you can either specify the Cloud VM Set you want to use interactively during the registration process or you can create a certificate for that Cloud VM Set in the KeyControl webGUI and then use that certificate during the registration process.

    To create the Cloud VM Set certificate:

    1. Log into the KeyControl webGUI using an account with Cloud Admin privileges.
    2. In the top menu bar, click Cloud.
    3. On the VM Sets tab, select the Cloud VM Set with which you want to associate the VM.
    4. Click Actions > Create New Certificate.
    5. If desired, enter a passphrase for the certificate. If you enter a passphrase here, you will need to enter that passphrase when you use the certificate on the VM.
    6. Enter a date on which this certificate should expire.

    7. Click Create. KeyControl downloads a .cert file to the default download location.

      Important: Do not rename the downloaded certificate. The name of the certificate has additional information, and a renamed certificate will fail.

    8. If necessary, copy the .cert file to the Windows VM.
  2. Log into the VM using an account with Administrator privileges.
  3. Open a Windows Command prompt and navigate to the directory in which you placed the .cert file. If you do not have a .cert file, you can register the VM from the any directory.

  4. Register the VM with KeyControl using the following command:

    hcl register [-a] [-h vm-name] [-d "vm-description"] [-p cert-passphrase] [-o one-time-passphrase] [-z cvm-set] [-n mapping-name] [-N] kc-hostname[:port],kc-hostname2[:port],... [cert-file.cert]

    where:

    • -a — Indicates that you want to authenticate the VM through the command line or the script instead of through a certificate file. Use this option if you are using Simplified or Automated Authentication. If you created a certificate in KeyControl, omit this option and specify the certificate name in cert-file.cert.
    • -h — The name of the VM that will be displayed in the KeyControl webGUI (Default: hostname).
    • -d — A description of the VM that will be displayed in the KeyControl webGUI.
    • -p — The passphrase assigned to the certificate when it was created. If you do not specify this parameter and the certificate has an associated passphrase, the registration process prompts you for the passphrase. Applies to Standard Authentication only.

    • -o — The one-time passphrase that will be used to encrypt the initial communication between this VM and the existing KeyControl cluster. If you do not specify this parameter, the registration process prompts you for the one-time passphrase. Applies to Standard Authentication only.

      Note: The passphrase is valid for 15 minutes from the time it is created. Make sure you authenticate the VM in KeyControl during this time. Authentication will fail after the passphrase has expired.

    • -z — The name of the Cloud VM Set defined in the KeyControl cluster to which you want to assign this VM. Applies to Simplified or Automated Authentication only (the -a option must be specified on the hcl register command).
    • -n — The name of the KeyControl Mapping that you want to associate with this VM. If you do not specify this option and one or more KeyControl Mappings have been configured, the Policy Agent prompts you to select a Mapping from the list. If you do not want to use a Mapping, you must manually respond to this prompt. This option is mutually exclusive with the -N option, described below, and it requires that the -a option must be specified on the hcl register command.
    • -N — Tells the Policy Agent that you do not want to use a KeyControl Mapping, even if one is available. If you specify both -N and -n, the Policy Agent ignores the -n option and does not assign a Mapping to the VM. Applies to Simplified or Automated Authentication only (the -a option must be specified on the hcl register command).

    • kc-hostname[:port],kc-hostname2[:port],... (required) — The list of IP addresses or hostnames for the KeyControl nodes with which you want to register the VM. You must specify at least one KeyControl node in this list. You must also specify a port if the KeyControl nodes use anything other than the default port (443).

      If you are using the the -n option to specify a KeyControl Mapping, this IP address will be the KeyControl node that the VM contacts to retrieve the Mapping information. After the Mapping has been retrieved, the Policy Agent ignores any other IP addresses in this list and only registers the VM with the KeyControl nodes in the contained in the Mapping.

    • cert-file.cert — The name of the certificate file you copied to the target system if you are using Standard Authentication. If you are running the hcl register command from a directory other than the one where the .cert file resides, specify the full path to the .cert file as part of this option. If you did not create a certificate file in KeyControl, omit this option and use the -a option instead.

Registration Examples with Standard Authentication

If the VM name is "hq-vm-3", the description is "HQ Windows 2012 Server", and you want to register it using Standard Authentication with two KeyControl nodes at 10.238.32.74 and 10.238.32.75, you would enter:

C:\> hcl register -h hq-vm-3 -d "HQ Windows 2012 Server" 10.238.32.74,10.238.32.75 \
      ad85837b-9862-11e1-afd5-000c29de5d41_120507163538.cert
You need to specify a passphrase that will be used for authentication with KeyControl
Enter passphrase (min 16 characters): passphrase16chars
			
Registered as hq-vm-3 with KeyControl node(s) 10.238.32.74,10.238.32.75
Please login to the KeyControl node to complete the authentication of this node

To register the VM in a single command where the .cert file resides in the directory /install/hytrust/cert, you would enter:

C:\> hcl register -h hq-vm-3 -d "HQ Linux Server Alpha" -p certpassphrase \ 
      -o onetimepassword16chrsmin 10.238.32.74,10.238.32.75 \
      ./install/hytrust/cert/ad85837b-9862-11e1-afd5-000c29de5d41_120507163538.cert

Registered as hq-vm-3 with KeyControl node(s) 10.238.32.74,10.238.32.75
Please login to the KeyControl node to complete the authentication of this node

Registration Examples with Simplified Authentication

In this example, the VM name is "hq-vm-3", the description is "HQ Windows 2012 Server", and the KeyControl node you want to use is at 10.238.66.250. You want to be prompted for the KeyControl Cloud Admin account information, the Cloud VM Set, and the KeyControl Mapping.

In this case, you would enter:

C:\> hcl register -a -h hq-vm-3 -d "HQ Windows 2012 Server" 10.238.66.250

Please provide the KeyControl login details
username: CloudAdmin
password: 

Available Cloud VM Sets
--------------------------------------------------------------------------------
SF-Datacenter
--------------------------------------------------------------------------------

Please specify Cloud VM Set to which this VM should be added: SF-Datacenter
Registered as hq-vm-3 with KeyControl node(s) 10.238.66.250

Completing authentication for hq-vm-3 on KeyControl node(s) 10.238.66.250

Authentication complete, machine ready to use
Getting KeyControl Mapping information


This VM can be added to one of the following KeyControl Mappings
--------------------------------------------------------------------------------
1 : SF-Datacenter-Map
2 : West-Coast-Map
--------------------------------------------------------------------------------

Please select a numeric KeyControl Mapping ID (0 to skip): 1
KeyControl Mapping: SF-Datacenter-Map
server description First Node, ip 10.238.66.250, port 443
server description Second Node, ip 10.238.66.251, port 443
Updated KeyControl list with KeyControl nodes 10.238.66.250:443,10.238.66.251:443

To specify the name, description, Cloud VM Set and KeyControl Mapping in a single command, you would enter:

C:\> hcl register -a -h hq-vm-3 -d "HQ Linux Server Alpha" -z SF-Datacenter -n SF-Datacenter-Map 10.238.66.250

Please provide the KeyControl login details
username: CloudAdmin
password: 
Registered as hq-vm-3 with KeyControl node(s) 10.238.66.250

Completing authentication for hq-vm-3 on KeyControl node(s) 10.238.66.250

Authentication complete, machine ready to use
Getting KeyControl Mapping information

KeyControl Mapping: SF-Datacenter-Map
server description First Node, ip 10.238.66.250, port 443
server description Second Node, ip 10.238.66.251, port 443
Updated KeyControl list with KeyControl nodes 10.238.66.250:443,10.238.66.251:443

Registration Example with Automated Authentication

If the VM name is "hq-vm-3", the description is "HQ Windows 2012 Server", and you want to register it using Automated Authentication with two KeyControl nodes at 10.238.32.74 and 10.238.32.75, you would create a registration script containing the following command:

C:\> hcl register -a -h hq-vm-3 -d "HQ Windows 2012 Server" -u htcloudadmin -s 'DogDays123!' \
      10.238.32.74,10.238.32.75
Certificate passphrase might be required
Certificate successfully unpacked

Registered as hq-vm-4 with KeyControl node(s) 10.238.32.74,10.238.32.75
Completing authentication for hq-vm-4 on KeyControl node(s) 10.238.32.74,10.238.32.75
Authentication complete, machine ready to use

What to Do Next 

If you used Standard Authentication, authenticate the VM with KeyControl as described in Authenticating a New VM. If you used Simplified or Automated Authentication, encrypt the drive as described in Data Encryption Overview.