Defining a new appliance

  • 6 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 SDP 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 New.

  • In the System Settings tab:

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

    • Interfaces - eth0 has DHCP enabled by default (along with DNS and Default Gateway), 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 such as other members of the Collective. This is configured per appliance just 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

    • pick a Site (or use the default)

    • System TLS Connections should be fine

    • In Secure Tunnel Settings, Allow Destinations require some value(s) or no tunneled traffic will be allowed out of the Gateway, so select <Add new>

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.

Use the <Export seed file/ISO> button which will be shown when you hover over any <Not active> appliance records in the admin UI.

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 using: sudo cz-config wipe-appliance --force

It is possible to seed an appliance manually if the situation requires it 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 move the seed to the appliance:

  • With SSH access, grab the seed using the RAW option (copies the JSON to the clipboard), then SSH in to the appliance and do nano seed.json, paste the seed, and then save.

  • For Cloud: 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: mount the seed ISO to the appliance using the Virtual Media function in the iDRAC.

  • For local hardware, use a USB drive:

Prepare a USB drive (FAT32-formatted). Any size will do.
Copy the seed to root of the USB drive.
If the appliance is not already running, power it on and wait a few minutes to let it start.
Insert the USB drive.
After a few minutes the Admin should be able to see the new appliance in the dashboard and the USB drive can now be removed.

  • For a virtual host: 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

For an existing appliance, the configuration settings will already exist and it will have already been activated. Deactivating an appliance can be useful when it needs to be removed from the Collective but will be re-added later, or when performing migration from one host to another. If you are migrating a Gateway, it is recommended to have another Gateway serving the same Site so migration will seamless for users.

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

  • Deactivate the appliance using the tools on the right-hand side. You cannot deactivate an active Controller; the Controller function must be disabled first.

  • To avoid having the new and old appliances claiming the same hostnames, either:

    • Power down the old appliance

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

At this stage, the appliance will no longer appear as Active in the Appliances page (System > Appliances). If migrating, refer to Activate the appliance to activate it.

Related articles