Defining a new appliance

  • 5 minute read
Prev Next

Once a Controller has been configured and set up, further appliances can be added to your Collective as required. These may be new appliances or a replacement appliance, for instance when migrating a Gateway from one virtual host to another. This section describes the process for defining a new appliance.

Before you start

  • At least one Controller must be online. Refer to Getting Started for more information.

  • The Controller must be configured with a working NTP server. Ensure the time and date are correct before proceeding by typing date from the command line.

  • The Controller must be able to receive inbound connections on ports 443 and 8443.

  • If you are not using the default Site you may want to configure another Site. This defines the protected network behind the Gateway. Refer to Sites for more information.

  • Ensure you have the correct admin privileges to add an appliance to the system See System Administration for more information.

Define a new appliance

Use the Appliances UI to define a new appliance.

For a new appliance, first the required configuration settings are set in the admin UI; then to activate your new appliance, you export the seed file. The seed file is a temporary initialization file containing information to allow trusted peer-to-peer communication to take place.

You have two options:

  • Add. Configure a new appliance from scratch:
    For example, when configuring the first Gateway in your AppGate ZTNA Collective, or configuring the first LogServer.

  • Clone. Create a duplicate of an existing appliance:
    For example, when creating another Gateway for a Site where many of the configuration details need to be the same. This option makes the process faster and helps to avoid errors in the configuration.
    To clone an appliance, select the appliance you want to clone. From the Editing Appliance page, select the <Actions> button and then select Clone.

To set up a new Gateway, in the Appliances page, select +Add.

  • In the System Settings tab:

    • Name and Appliance Hostname/IP (or enable Automatic Hostname/IP Assignment) are the only required fields. See Controllers and system security for recommendations about use of hostname vs IP address.

    • For Interfaces, eth0 has DHCP enabled by default, with options for NTP and MTU. A static IP address might be better for a Gateway.

    • DNS Servers will be used by the appliance operating system to resolve these hostnames. This is configured per appliance in case alternative services such as AD or RADIUS need to be configured to support HA deployments in different locations.

  • In the Functions tab:

    • Enable Gateway.

    • Select a Site or use the default.

    • Leave System TLS Connections as is.

    • In Secure Tunnel Settings, the Client Tunneling - Allowed Destinations field requires some value(s) or no tunneled traffic will be allowed out of the Gateway. Select +Add to configure values.

At this stage, the appliance status will be Not Active in the Appliances list. You will need to activate the appliance.

Other appliance types follow their own specific set up procedures within the Functions tab.

Activate the appliance

Use the Appliances UI to export the seed.

Export seed file/ISO

Once the new appliance record has been created within the admin UI, you'll need a seed file to activate the target appliance.

To export the seed file:

  1. Navigate to Appliances (System > Appliances).

  2. Hover over the newly-created appliance in the list and select Export Seed File/ISO.

A screenshot of the Appliances page showing the Export Seed File/ISO button.

NOTE

It is not possible to seed a newer target appliance than the Controller version you are using to export the seed.

Activate the appliance

If it hasn't been done already, you will need to perform an appliance installation on a physical/virtual host or use a cloud instance of the appliance. Make sure you have SSH access to the new appliance and that it has access to the Controller on port 443.

When the new appliance finds a valid JSON (or ISO) seed file, it will automatically activate. The seed file remains valid only for the Seed Lifetime that was selected. The installation guides and cloud documentation provide specific details about how to seed the appliance at the same time as it is created. It is also possible to seed an appliance manually (see below) once it is up and running.

  • After a new appliance has been seeded, it will establish communication towards the Controller. As part of the registration it will get a signed certificate and change its status from pending to active.

  • Once activated, the temporary certificate included in the seed file is deleted. This means a seed file can only be used once (if activation succeeded) so a new seed file will have to be generated to reactivate it.

  • Once communications are established, the Controller messages the appliances (for instance; asking for health status or telling Gateways which tokens are no longer valid).

Manual seeding of an appliance

If you are re-seeding an existing appliance, you may need to wipe it before it will accept a new seed file. This can be done by using the command sudo cz-config wipe-appliance --force

If you need to seed an appliance manually, you do this by passing the seed to the appliance.

NOTE

If you download the JSON seed file, it may be renamed but must end in -seed.json or be exactly seed.json

To pass the seed to the appliance:

With SSH access:

  1. Grab the seed using the RAW option which copies the JSON to the clipboard.

  2. SSH in to the appliance and enter nano seed.json, paste the seed, and save.

For the Cloud:

  1. Upload the seed using SCP to the appliance. For example: scp -i ~/keys/mykey ~/Desktop/newgateway-seed.json cz@newgateway.wherever.com:

For remote hardware:

  1. Mount the seed ISO to the appliance using the Virtual Media function in the iDRAC.

For local hardware:

  1. Prepare a FAT32-formatted USB drive. Any size will do.

  2. Copy the seed to root on the USB drive.

  3. If the appliance is not running already, power it on and wait a few minutes to let it start.

  4. Insert the USB drive.

  5. After a few minutes, the admin should see the new appliance in the dashboard. The USB drive can now be removed.

For a virtual host:

  1. Mount seed ISO to virtual machine.

cz-configd should detect this file and automatically register the appliance. The appliance will report Appliance seed configuration file picked up at /home/cz/seed.json.

If this does not happen, restart cz-configd by entering: sudo service cz-configd restart

Deactivate/Migrate an existing appliance

Use the Appliances UI to deactivate an appliance

You can deactivate an appliance when migrating it from one host to another, or for removing an appliance from a Collective that you intend to reactivate in the future.

If migrating, the existing appliance needs to be deactivated and taken offline; the seed file is then re-exported for the new appliance.

NOTE

If you are migrating a Gateway, it is recommended to have another Gateway serving the same Site to ensure that migration is seamless.

To deactivate an appliance:

  1. In the Appliances page, select the three dots next to the appliance and select Deactivate.

NOTE

You cannot deactivate an active Controller. The Controller function must be disabled first.

  1. To avoid having the new and old appliances claim the same hostnames:

    • Power down the old appliance; or

    • Wipe the appliance using the command: sudo cz-config wipe-appliance --force

The appliance will no longer appear as Active in the Appliances page. If migrating, refer to Activate the appliance to activate it.

Related articles