Documentation and help portal

regify Provider Manual

Installation

The regify provider appliance herein referred to as the 'appliance' or 'provider' is a ready to install and use turnkey system. It requires no Linux knowledge, even though it runs on a specialised CentOS 7 Linux system. The following concepts must be understood by the person installing and configuring this appliance:

  • Basic knowledge of IPv4 numbers, host names and DNS

  • Basic conceptual MTA configuration knowledge.

Requirements

A dedicated hardware machine or VMware virtual machine with the following attributes:

The ISO image can be burned onto a CD and then installed by booting off the CD. If the machine is a virtual machine then the virtual CD can be pointed at the ISO itself.

Before installing the system it is helpful to provide a few basic things:

  • IP number for the system including the net mask

  • Fully qualified domain name for the host

  • Fully qualified domain name for the server. This can be the same as the host name, but must be resolvable via DNS

Third party software

Installation of driver software and programs in the context of virtualisation technologies

regify also provides support for customers who use the regify provider software appliance or the regigate software appliance on virtual servers (e.g. on VMWare, VirtualBox or Microsoft Virtual PC) according to the maintenance agreement and in line with commercial practice. As virtualisation technologies emulate functions of physical computers, regify assumes that regify products work in virtual environments as they do in physical environments. Therefore, provisioning of the regify support is based on the assumption that apotential problem or error that is observed in a virtual environment can be replicated in a physical one.

A regify customer may install other software on a regify appliance if such software is critical for the operation of the virtual environment. The existing maintenance agreement between customer and regify also applies for such virtual setups. However, problems or errors that only occur on virtual systems or in combination with software that was installed by the customer are not covered by the maintenance agreement. In such cases, regify reserves the right to charge the customer for time and effort. Moreover, regify does not assume any liability for system failure or loss of data.

System Installation

Insert the CD into the computer and boot off of it. At the first boot: prompt simply press enter. This will automatically install the entire system and reboot into the appliance wizard. If you are installing using a serial connection type serial and press enter at the boot: prompt. To use the serial connection insure your client the BIOS to use the following settings.

Serial: Port 0
Baud: 115200
Parity: None
Databits: 8
Flowcontrol: None
Then after the reboot wait for the login prompt.
CentOS Linux release 6.0 (Final)
Kernel 2.6.32-71.29.1.el6.i686 on an i686

localhost.localdomain login:

Login to the appliance as user regify password regify.

Appliance Wizard

The first page in the appliance wizard is the end user license agreement (EULA). If it is not accepted, the system will shut itself down. Subsequent reboots will land on the same page. After reading the EULA simply press Tab to move the focus to the Accept button and press Enter.

wizEula

The second page allows you to choose the database back end. MariaDB is the better choice for the clearing appliance due to performance reasons. So simply TAB to Yes and press Enter. One thing to note is that the back end cannot be changed at a later time. In the case of multiple clearing databases participating in a replication scheme, all databases need to be of the same type.

wizChooseDb

From here on the wizard pages can be repeated at any time by choosing Appliance Settings  Run appliance wizard from the appliance menu.

Here you choose your keyboard layout. It only matters when logging in locally, but is important for getting the passwords right. You can use the Arrow keys to choose your layout and hit Tab to choose the Next button.

wizKeyboard

Next we have the basic network configuration to be entered.

wizIp

This page allows setting of the host name. While it is not strictly necessary, it is usually better to have the host name resolvable via DNS, because missing or mis-configured DNS can lead to strange and hard to troubleshoot problems.

wizHostname

This dialogue is used to set the password for the regify appliance user. This is the account used to administer the regify provider appliance. The login account is called regify and the password is set in the dialogue below.

regifyPw

Here is another password dialogue, but this one is for the appliance root account. Unlike the regify user the root user has complete control over the appliance and should therefore not be used for day to day administration.

rootPw

Here you set the administrative e-mail address. This address may receive occasional e-mail from the system.

adminEmail

Here you can choose the time zone your appliance is in. If you set the BIOS system clock to UTC instead of local time check the System clock uses UTC option.

timeZone

Provider Configuration

This dialogue asks for the server name. The server name is what the user types into the web browser to visit the portal. So if the user goes to https://regify.providername.com/. Then the server name should be regify.providername.com. While this can very well be the host name, it can also differ in the case where the host lies behind a load balancer and is one of many. There the host name might be something like web1.providername.com through web4.providername.com but all 4 servers would have the same server name.

wizServerName

This dialogue asks whether the server will use SSL or not. If it is behind a session terminating load balancer answer Yes here and the server will be configured to use HTTP only.

wizLb

In case the answer was Yes, you will have to specify the load balancer IP or subnet that is allowed to connect to this server, as it is not acceptable for the public to connect without SSL.

wizLbIp

For machines that use SSL, an initial self signed cert is created here. The visitors of the portal will see these values when they inspect the certificate.

wizCertReq

After creation you are informed to come back using an SSH session to administer the key. This is because the keys are copied and pasted in to the SSH terminal, and this is typically not possible on the console. See the SSH Terminal section for details.

wizSelfSignedInfo

At the end of the wizard diagnostics are run to make you aware of potential issues that need to be remedied, before the system can function properly. Here is an example result.

wizDiag

At the end of the wizard you are informed as to where to go to configure your provider installation.

wizFinish

SSH Terminal

Most users use Windows systems. Unfortunately these systems lack terminals and SSH clients. Fortunately there are third party applications available. One such application is called PuTTY and is available for free. You can download it here http://www.putty.org/ . PuTTY does not need to be installed. It can simply be placed onto the desktop and run by double clicking it.

PuTTY Configuration

While PuTTY is free and generally works well, it can be a little quirky in the initial configuration. This is why it is covered in detail here. I will setup a configuration for the regify user. I will now go through and make the adjustments needed to connect to the appliance provider2.de.regify.com as the user regify. When initially opening PuTTY you get the following screen.

puttyConf

Adding regify as the Auto-login username under Connection  Data saves you from having to type it every time.

puttyLogin

Setting the Remote characters set under Window  Translation to UTF-8 is important.

puttyCharset

If it’s not set to UTF-8 you’ll get a screen that looks like this.

gooblygook

IMPORTANT:This step is very important and frequently forgotten.

After setting the Host Name, set Saved Sessions and press Save, not Open. This will save these settings for you to use next time.

puttySave
If you only press Open, PuTTY will forget everything and you’ll have to do this again.

After pressing Save simply double click the new provider2 entry to open the session.

puttyOpen

The first time you connect, you will get a prompt that looks something like this. Simply click Yes (Ja).

puttyAlert

Now you are prompted for the password for the regify user that you set earlier in the appliance wizard. Enter it here. It will not echo it back, not even as stars. Press Enter when done.

puttyRegifyLogin

Now you are logged in as the regify user and can administer the appliance. Hitting Tab twice followed by Enter will exit the session again.

Appliance Menu

Overview

In general an appliance entry that ends with …​ indicates that there is a sub menu structure below the given item. Pressing F8 backs out of dialogues and sub menus, but does not exit the appliance menu. This allow for quickly pressing F8 to get to the top level of the appliance menu without running risk of logging yourself out.

ClearingMenu

The appliance menu is separated into several major sections and the update functionality. The update functionality handles installing updates to the appliance in a wizard like manner.

The major sections are:

  • Network - handles IP related matters

  • Appliance - appliance configuration like time password, reboot…​

  • Database - start/stop database, configure replication

  • Provider - Web server related items

These are covered in greater detail in the following sections.

Network

Even though the appliance menu protects against this, care needs to be taken in this section when connecting remotely. When changing IP numbers remotely it is best to first add the new IP, disconnect and log back into the machine using the new IP, and then deleting the old IP.

netMain

View Settings

The Network Settings  View Settings page gives you a general overview of the network settings. It lists the host name, all configured interfaces and DNS servers.

netView

Run Diagnostics

Since there are many things that can be done incorrectly between DNS entries and server configurations, a diagnostics tool is installed that aims to point out common mis configurations and their remedies. It can be found under Network Settings  Run Diagnostics.

netDiagnostics

In this screenshot everything is correct, except for the fact that this internal machine used for making these screen shots is not accessible from the internet.

diagOk

Add IP

Network Settings  Add IP allows you to do just that. Interface lists the available network adaptors. The (on) suffix means it’s plugged in, while (off) means it is not. Simply choose the Interface, specify the IP Number and Netmask and hit Ok. If you are running an 802.1Q VLAN, add the proper VLAN ID, otherwise just leave this field blank. The network will get restarted making the change immediate. This will take a second or 2 to complete.

netAddIp

Set Gateway

Network Settings  Set Gateway allows you to set the default gateway for the system. Simply type in the IP number of the gateway Tab to Ok and press Enter.

netGw

Set Hostname & DNS

Network Settings  Set Hostname & DNS allows you to specify the Hostname and up to 2 DNS servers. The DNS servers can be safely omitted to use the built-in internal DNS server. It is good practise but not mandatory for the given host name to be resolvable by the given DNS entry.

netHostDns

Advanced Settings

Network Settings  Advanced Settings to take advantage of some of less used features of the appliance.

netAdv

SSH Settings

By default SSH root login is disabled and general access is only allowed from the local subnet. This is for security reasons. At Network Settings  Advanced Settings  SSH Settings you may specify one or more space delimited IP numbers or subnets to access the appliance. The following entries are legal and equivalent:

  • 192.168.11

  • 192.168.11.0/24

  • 192.168.11.134/24

Or:

  • 192.168.11.134

  • 192.168.11.134/32

You may check Allow root login if needed. This is only needed to setup database replication or High Availability.

netSsh

Remove IP

Network Settings  Advanced Settings  Remove IP allows you to remove an IP number. It is fine to do this over the network since it will not allow you to remove the IP number with which you are logged in as. Use the Arrow keys to select 192.168.11.137 and hit Tab twice to get to the Delete IP button and hit Enter.

netDelIp

Proxy Settings

Network Settings  Advanced Settings  Proxy Settings allows you to specify a proxy server to use when making HTTP or HTTPS calls to for example the update repository or the clearing server. This can be in the format of PROTO://HOST:PORT or simply HOST:PORT.

netProxy

Combine Interfaces

Starting with version 3.4.0, it is possible to visit Network Settings  Advanced Settings  Combine Interfaces to aggregate 2 or more network interfaces into one logically bonded network interface. This provides added high availability through redundancy, as well as scalability through link aggregation. For example, by combining 3 1Gb links a single 3Gb link is achieved. This link will continue to function as long as any of the 3 links are functional. By running each link through its own switch, switch redundancy will also be accomplished. The appliance currently supports 3 modes of link aggregation.

  • 0 - Round Robin Balanced

  • 4 - 802.3ad Link Aggregation (the switch must support it)

  • 6 - Adaptive Load Balancing

All 3 modes must be support by the other end of the link, while mode 4 must also be supported by the switch. Any recent Linux kernels will support these link aggregation schemes. Only interfaces that have not been configured with an IP number are available for bonding. Interfaces that participate in link aggregation are not available for individual configuration.

netBond

After eth1 and eth2 are combined, they may be configured as bond0.

eth1 and eth2 are no longer available for IP configuration.
netAddIpBond

Separate Interfaces

Aggregated links may be separated here.

netUnbond

When deleting a bonded interface, you will be prompt to accept that the IP numbers that were configured on the interface in question will be deleted. If an IP number held by this interface is used by a service, or the connection address of the current SSH session, it will not be deleted. In the service case assign another IP number or temporarily shut down the web server. Be sure to update the web service with the proper new address afterwards.

netUnbondConfirm

Appliance

The Appliance Settings section handles things that pertain to an individual machine.

appMain

Run appliance wizard

Appliance Settings  Run appliance wizard can be used to run through the appliance wizard again. There is no harm in running it more than once and it provides a coherent alternative to making changes in the appliance menu.

Time & Locale

Use Appliance Settings  Time & Locale to set Localisation Settings.

appTimeLocale

View Time Settings

The Appliance Settings  Time & Locale  View Settings dialogue shows the state of the NTP daemon as well as the current time and time zone. Below is a listing off its current peers:

timeView

Keyboard Layout

In Appliance Settings  Time & Locale  Keyboard Layout you can change the keyboard layout for the console. Use the Arrow keys to choose the layout and press Tab to switch to the Ok button and hit Enter.

This setting has no influence on PuTTY or other remote sessions.
appKeyboard

Select Timezone

Use Appliance Settings  Time & Locale  Select Timezone to select the time zone the system is in. Use the Arrow keys to choose the time zone and press Tab to get to the checkbox. If the systems BIOS hardware clock is set to UTC instead of local time, check the System clock uses UTC option by pressing Space. Press Tab to switch to the Ok button and hit Enter.

appTz

Set NTP Servers

The Appliance Settings  Time & Locale  Set NTP Servers setting show up when NTP is enabled only. It allows you to specify one or more NTP server host names or IP addresses. Servers may be specified one or more per line. When specifying more than one per line separate them with spaces.

appNtp

E-mail Settings

Visit Appliance Settings  E-mail Settings to set anything relating to sending e-mails.

If you’re running a regigate, these settings will not apply to the individual regigate routes. This is only for internal appliance MTA like regify provider messages and system email.
appEmail

Set Administrative E-mail

The Appliance Settings  E-mail Settings  Set Administrative E-mail allows you to set the administrative e-mail address. This address may receive occasional e-mail from the system.

appAdminEmail

Set E-mail Smarthost

In some configurations it is not possible for a given server to send e-mail by itself. To accommodate this situation, you may use Appliance Settings  E-mail Settings  Set E-mail Smarthost to tell the server to route all SMTP (e-mail) traffic through the given host.

appSmartHost

Set E-mail Hostname

Appliance Settings  E-mail Settings  Set E-mail Hostname dialogue can be used to override the default host name, the appliance MTA (Mail Transfer Agent, aka E-mail Server) claims to be. This is necessary when an appliance is located off limits to the internet.
It is important to insure that this name has the following properties:

  • A reverse DNS lookup of the outgoing IP address has to resolve to the name specified here. The outgoing IP address is the address an outside MTA sees when this machine connects to it.

  • A forward DNS lookup of this name should result in the above mentioned outgoing IP address.

When one or more of these requirements are not met, it is likely that e-mail from this machine will be marked as spam or not be delivered at all.

appMtaHostname

Other Settings

Visit Appliance Settings  Other Settings for support diagnostics and other system maintenance work.

appOther

Support Diagnostics

This menu allows you to send comprehensive but not sensitive system information to regify support. Should you feel that your system setting are sensitive, you may send this information to yourself and then forward it via regimail to regify support. If even that is insecure, then log onto the console as root and run regifyInfo. Then copy the output and send it via regimail to regify support.

appSupportDiag

Drop into shell

Appliance Settings  Drop into shell provides the regify user with a command line shell to perform advanced operations. Unlike normal administrative appliance tasks, these operations do require Linux knowledge and are not recommended, unless you know what you are doing or are directed by regify technical staff to do so. As it already says, you can type exit to return to the appliance menu. Usually pressing Ctrl+d by itself will also return you to the appliance menu.

appShell

Reboot the appliance

As you might have guessed, Appliance Settings  Reboot the appliance does just that.

Set root password

Appliance Settings  Set root password to change the password for the root account. For security reasons, the old password must be supplied to create the new one. The password must be at least 8 characters long and contain letters and numbers, but no special characters.

appRootPw

Set regify password

Use Appliance Settings  Set regify password to change the password for the regify account. For security reasons, the old password must be supplied to create the new one. The password must be at least 8 characters long and contain letters and numbers, but no special characters.

appRegifyPw

Database

This menu is somewhat dynamic and shows applicable options based on the chosen configuration. Below are the options visible when the local database is enabled.

dbMain

View Database Status

The Database Settings  View Database Status dialogue gives you a general idea about the current database status.

dbStatus

Set Database Account

Database Settings  Set Database Account allows you to set the user name and password the provider application will use to connect to its database. As pointed out in the dialogue this should ideally be the same credential on all machines if replication is enabled, as the account credentials are replicated as well.

dbAccount

Start/Stop Database

The Database Settings  Start/Stop Database option allows you to temporarily start or stop the database and also tells you whether it’s running. Like the other Start/Stop options in the appliance menu, the Stop Database option is present when the database is running, while you get the Start Database option when it is not.

Configure Replication

The Database Settings  Configure Replication page allows you to setup and change replication settings. After making achoice, a mini wizard is started to present you with the relevant dialogues. These are described in detail below.

It is important to always set replication on all involved systems. When recreating replication scenarios, the first step is always to configure each system to no replication. Then setup your new replication scheme following the steps below as far as they apply.
dbReplication

Master Replication

The Database Settings  Database Replication  Master Replication dialogue is used to setup the master of a replication scheme. Every server in a replication scheme needs to have a unique server id. This number should usually range from 1 to the number of servers involved in the replication scheme. Both Slave Settings and Master Settings dialogues contain the Unique Server ID to supply this number. The Slave Host IP field is used to set the IP number or subnet of the slave host(s) that will be connecting to this master for replication updates.

The field accepts IP numbers or networks in the form of:

  • 192.168.11.134

  • 192.168.11

  • 192.168.11.0/24

It does not accept:

  • host names

  • 192.168.11.0/255.255.255.0

  • a missing entry

The Replication Username and Replication Password fields contain the credentials the slave must use to connect to this master database.

dbMasterRep

Slave Replication

The Database Settings  Database Replication  Slave Replication dialogue is shown when the database acts as a slave. This is the case the when Slave or Cross Master is selected in the Database Settings  Configure Replication dialogue.

Every server in a replication scheme needs to have a unique server id. This number should usually range from 1 to the number of servers involved in the replication scheme. Both individual Slave Replication and Master Replication dialogues contain the Unique Server ID to supply this number. If you chose Database Settings  Database Replication  Cross Master, the slave dialogue will not display the field, because the information was already collected in the Database Settings  Database Replication  Master Replication dialogue. The Master Host IP fieldcontains the IP number of the server to pull the replication data from. This may not be a subnet. The Connection Username and Connection Password fields contain the credentials the slave uses to connect to the master database. It needs to correspond to what was set in Replication Username and Replication Password on the Master Replication dialogue on that host.

dbSlaveRep

Replication Synchronisation

Replication Synchronisation is a helpful feature to initially setup, or at a later time restore, broken replication configurations. This option is only available when the system acts as a replication master. This is the case when Configure Replication is set to Master or Cross Master replication. Replication Synchronisation uses SSH to synchronise the two systems. It is necessary to use the root account and password of the other system to accomplish this. This is one scenario where the system root account is actually used. It is necessary for root SSH login to be enabled on the slave system. To enable it, log into the other system as the user regify and go to Network Settings  Advanced Settings  SSH Settings and check the Allow root login option.

dbRepSync

The Slave Host IP field takes the IP number of the slave host. Note that this field defaults to the setting specified in Database  Master Settings  Slave Host IP and may be a subnet in the form of 192.168.11.0/24 in which case it needs to be adjusted to point to the actual host. The Root Password field expects the root password of the slave host.

dbRepSyncCreds

Because this process can take a considerable amount of time, a progress bar is displayed.

dbRepSyncProgress

Example: Cross Master Replication

The following table describes the settings chosen on two example systems running in a cross master replication scheme. The first system has the IP number 192.168.1.1 and the second is 192.168.1.2.

If restoring a previously broken cross master replication scheme, it is necessary to first set both machines to No replication in order to bring them to a known state.

Deploying this replication scheme is best done using the following steps:

Machine Info

IP Number

192.168.1.1

192.168.1.2

Database Replication

Cross Master

Cross Master

Master Replication

Unique Server ID

1

2

# of Servers

2

2

Slave Host IP

192.168.1.2

192.168.1.1

Replication Username

replicator

replicator

Replication Password

SomePassword

SomePassword

Slave Replication

Master Host IP

192.168.1.2

192.168.1.1

Connection Username

replicator

replicator

Connection Password

SomePassword

SomePassword

Replication Synchronisation

Yes

No

Disable Database

The Database Settings  Disable Database option is only available when replication is disabled. Exercising it disables the Database. In this case the provider application needs to be configured to point to a remote database.

dbDisable

Enable Database

Database Settings  View Database Status, Database Settings  Enable Database and Database Settings  Set Database Account are the sole entries of the Database section when the local database is disabled. Exercising the Database Settings  Enable Database option turns on the local database. But does not setup any accounts for the provider application to use.

dbEnable

Set Database Account

When the local database is disabled the Database Settings  Set Database Account dialogue includes host settings for the remote database.

dbSet

After setting the remote database you are presented with the opportunity to create the database account on the remote database.

dbCreateAccount

Create provider Database Account

The Create provider Database Account dialogue requires the credentials of a user that is allowed to create user accounts on the remote database. The database access mask describes from which hosts the account can connect. "%" is a wild card and means any host. A setting of 192.168.1.% means all hosts on the 192.168.1 subnet can connect using this account.

dbCreateAccountSettings

Provider

This section entails everything provider related. Like the database section, this section varies depending on whether SSL is used not. Below is the non-SSL version.

provMain

Using SSL

Switching to SSL requires one IP address for the main provider as well as each sub provider. In the first dialogue you assign each sub provider an IP number.

provSslIp

You will get prompted to create self signed certificates for any provider that doesn’t already have one. The flow is the same as it is in the wizard.

wizCertReq
wizSelfSignedInfo

Here is the Provider Settings menu when SSL is enabled.

provMainSsl

Start/Stop Web Server

Provider Settings  Stop/Start means if the service is running you get the Provider Settings  Stop Web Server option, if it is not you get the Provider Settings  Start Web Server option, meaning these options also serve as an indicator of whether something is running or not.

Configure regibox

regibox consists of meta data and file data. While the meta data resides in the database and is replicated over all provider systems behind a load balancer via MySQL replication, the file data must reside on a commonly accessed SMB network share. High availability and redundancy must be managed internally by the network share hoster. This dialogue needs to be completed on each provider node to enable it to offer regibox functionality. While the Windows Domain field is optional, all other fields are mandatory, meaning the share has to require user credentials. The share should exclusively host regibox functionality, to prevent file locks and other potential instabilities. All data on the share is encrypted.

provRegibox

Backup Options

Provider Settings  Backup Options allows you to automatically backup the provider database and configuration file. These backups are important in case data loss has occurred. The Backup Options are organised in a 2 step mini wizard. The first screen obtains and tests the settings for the share where the backups are to be copied to . These settings are validated to insure that writing to the specified share is indeed possible. If an error occurs an e-mail will be sent to the administrative e-mail specified in the appliance wizard or Appliance Settings  E-mail Settings  Set Administrative E-mail screen. Tab to the Disable Backups button to turn automatic backups off again.

provBackup

The second screen collects information regarding scheduling and backup retention. The Interval option sets whether to run backups every 1,6 or 24 hours. The Start Time setting specifies at which minute, and with the 6 and 24 hour intervals, which hour, the backup is to be run. When Interval is set to Every 6 Hours and the Start Time is set to 23:15, backups will be made at 5:15, 11:15, 17:15 and 23:15. The Backup Retention setting can be used to delete backups after a week or month. When it is set to Forever, no backups are ever deleted and the administrator must ensure that adequate disk space is provided.

provBackupSchedule

Restrict Admin Access

This dialogue makes it possible to restrict access to https://regify.providername.com/ADMINISTRATION/ to a limited set of IP numbers or subnets. It is optional, but highly recommended for locking down the administrative section, in order to protect it against potential password attacks. Leaving the field blank will allow access to any IP number.

provRestrictAcc

Add Subprovider

In SSL mode you can only add a sub provider if you have an available IP for it. The first step is to choose which IP to use.

This screen does not appear without SSL mode.

provChooseIp

The second step is to choose the provider domain name. In non-SSL mode this is the only screen presented to you.

provServerName

In SSL mode you are also prompted to create a self signed certificate, unless one already exists. This screen does not appear without SSL mode.

wizCertReq

This is followed by the notice about the self signed certificate. This screen does not appear without SSL mode.

wizSelfSignedInfo

Delete Subprovider

The main provider cannot be deleted. It is therefore not listed.

provDeleteSub

Deleting a sub provider is a major change that is not commonly done. That is why you are prompted to type in the random character sequence to confirm the deletion. The idea is to prevent accidental deletion.

provDeleteSubConfirm

Edit Subprovider

To make changes to a given provider or subprovider, you first choose which provider to operate on. The * indicates the main provider.

provChooseSub

After choosing you will get the following menu in SSL mode.

Server Name

The Provider Settings  Edit Provider  Server Name page does the same thing as its wizard counterpart. When the server name is changed the server’s SSL certificate may need to be updated. Be sure to also update the DNS entry to reflect the new name.

provSub
provServerName

In SSL mode you will be prompted to create any missing certificates.

wizCertReq

Create New SSL Cert

This dialogue allows you to create a completely new key and certificate pair. It is similar to the Show Cert Request dialogue but allows you to create a new key. Unlike the Show Cert Request dialogue Create New SSL Cert will impact a running system and should only be used when the private key has been compromised.

clrCertReq

Choosing No here will abort the procedure; while Yes will create a new self signed certificate.

clrConfirnCert

Choosing No will leave the old key intact; while Yes will create a new one.

clrConfirmKey

After this the new certificate will need to be signed again.

Show Cert Request

Signing a server certificate is something that is done on a single server install or on one of many servers running in a cluster. For the remaining machines in a cluster see Provider  Edit Provider  Provider Name  Import Cert & Optionally Key. I will cover the process of getting the certificate request and importing the signed certificate using PuTTY. First choose Provider  Edit Provider  Provider Name  Show Cert Request. This will first give you the opportunity to change the certificate subject.

wizCertReq

Then it will bring up something like this.

provCertReq

When the upper section is selected using PuTTY, it also means, it has been copied to the clipboard. There’s no need to right-click or press Ctrl+c or Ctrl+Insert. Simply press Enter after the certificate request has been selected.
Now go and paste the certificate request into wherever your SSL Certificate provider tells you to. This could be a file or a web form. After you have received the certificate from your certificate provider, import it using the Provider  Edit Provider  Provider Name  Import Cert & Optionally Key option.

provImportCert

Copy the signed certificate into the clipboard and right click on the PuTTY terminal window to paste it in. If your certificate was signed by an intermediate certificate, be sure to include the complete certificate chain, which your provider should provide you with. Certificate and chain must be in PEM format and can be pasted into the terminal in any given order. To be on the safe side press Enter between multiple paste operations to ensure that each certificate starts on its own line. Press Ctrl+D to complete the operation once everything has been pasted into the terminal.

provImportCertPaste

If you have successfully imported the signed certificate you’ll see a screen that looks somewhat like this one.

provImportResponse

Import Cert & Optionally Key

This dialogue is used to import either a signed certificate originating from a certificate request created by this server, or a complete key and certificate created and exported from somewhere else. Complete import is usually the case when you have a cluster of machines that all use the same SSL certificate. After getting the first certificate signed, you visit Provider  Edit Provider  Provider Name  Export Key & Cert. First you copy the certificate from there, and then import it on the other machines by visiting Provider  Edit Provider  Provider Name  Import Cert & Optionally Key.

provImportCert

Regardless of whether it was an export or you just got a certificate request signed, simply copy the contents into the clipboard and right click on the PuTTY terminal window to paste it in. The content must be in PEM encoded format and can be pasted into the terminal in any given order. To be on the safe side press Enter between multiple paste operations to ensure that each certificate starts on its own line. Press Ctrl+d to complete the operation once everything has been pasted into the terminal.

provImportCertPaste

If an encrypted key is included, you will be prompted for the password.

provImportPw

If you have successfully imported the signed certificate you’ll see a screen that looks somewhat like this one.

provImportResponse

Export Key & Cert

This option allows you to export the complete SSL key and certificate for backup purposes or for re-importing it on another machine using Import Cert & Optionally Key. For security reasons the appliance will not give out the private keys unencrypted. Choose a good password and remember it, as you will have to provide it when you want to import the key and certificate somewhere.

provExportPw

After entering a key password you will be presented with the key and certificates in PEM format to be copied out using the clipboard. You will most likely have to scroll up to the section that starts with the private key and then select everything below that by moving the mouse at the bottom of the PuTTY window until you’ve reached the end. Then paste it into a file.

provExport1
provExport2

Enable regigate Connector

This option is available only under the following conditions.

  1. The provider is installed and configured. i.e. the web wizard has been run.

  2. The regigate connector for this sub provider is not enabled.

Exercising this option enables the regigate connector for this sub provider. You need to visit the https://Provider Name/ADMINISTRATION/ and click Gateway management to white list remote regigates and sign their certificate requests.

If load balancers are used, they must not terminate the TLS connection.

This option is available on a per provider basis and multiple sub providers may run concurrent regigate connectors. regigate connectors require a TLS connection. No sessions are used so no state management is required by the load balancer.

provEnableGwConn

Running regigate Connectors on multiple Machines

To enable the regigate connector on multiple provider server installations configured in a cross master configuration, go to each appliance menu and visit Provider  Edit Subprovider  Provider Name  Enable regigate Connector. Then visit https://Provider Name/ADMINISTRATION/ and click on Gateway management. This link is only available if the regigate connector is enabled on that server. Any changes made to these pages are automatically replicated to all provider machines in the cross master replication.

Likewise, to disable the regigate connector, simply visit Provider  Edit Subprovider  Provider Name  Disable regigate Connector on each machine. No further action is needed.

If the regigate connector has been disabled and then re-enabled on any of the machines in the cross master replication, it is necessary to visit https://Provider Name/ADMINISTRATION/ and click on Gateway management. There the last enabled regigates will be displayed. To re-enable them simply press Save Changes and they will be enabled on all machines.

Replication may take up to 5 minutes. To synchronize the changes immediately visit https://Provider Name/ADMINISTRATION/ and click on Provider maintenance. Then press Synchronize now. Repeat this process for every server in the replication ring.

Disable regigate Connector

This option is only show if the regigate connector for this sub provider is currently enabled. Exercising it disables the regigate connector, but does not remove individual regigate entries made in the web GUI under Gateway management. This means that if the regigate connector is disabled and subsequently re-enabled, visiting Gateway management and pressing Save Changes will restore the initial state.

provDisableGwConn

Stop using SSL

If no regigate connectors are enabled and SSL is on, you can choose Stop using SSL and get a screen prompting you to set the load balancer IP or subnet that is allowed to connect to this server, as it is not acceptable for the public to connect without SSL.

provLbIp

Example: Adding a subprovider with cross master configuration

The following steps describe how to add a subprovider in a cross master replication scenario. We will assume that the machines are called host1 and host2 and that the new provider is called provider2.

  1. Visit each host and add an additional IP number. This is needed when the provider either terminates its own SSL connections or the regigate connector is enabled.

  2. Visit the appliance menu of host1 and go to Provider Settings  Add Subprovider.

  3. Choose the right IP number if SSL is used.

  4. Choose provider2 as Server Name.

  5. Fill out the certificate request, if presented.

  6. Visit Provider Settings  Edit Subprovider  provider2  Show Cert Request to copy the certificate request.

  7. Get the certificate request signed.

  8. Import the signed certificate request or complete PEM formatted key pair if the request was generated elsewhere.

  9. Visit Provider Settings  Edit Subprovider  provider2  Export Key & Cert to export the servers key pair. Provide a password and copy the key pair some place safe.

  10. Visit Provider Settings  Edit Subprovider  provider2  Import Cert & Optionally Key on host2.

  11. Paste the key pair from host1 into the window and supply the password provided earlier.

  12. Press OK to the IP Error.

  13. Visit Provider Settings  Edit Subprovider  provider2  Server IP and choose the IP number for the new subprovider.

After this you will be able to administer the newly created subprovider as usual by pointing your web browser to https://provider2/ADMINISTRATION/.

Updates

The top entry of the appliance menu is Check for updates. When that option is exercised the system will consult updates.regify.com to see if there are new patches for your current version and whether there is a new major version available. You will be prompted to confirm each after which the system will install what you have confirmed. If you choose No to all upgrades, the system will remain unchanged.

updatesPatch

If you have upgrades that you want to install, you will get to follow the installation progress and are prompted to press enter at the end, to return to the appliance menu.

updatesProgress

If the appliance menu has been updated, you will be prompted to reload it by simply pressing Enter.

The appliance can only upgrade one major version at a time.

This means that after you have upgraded to a new version, it will automatically check for the next version. If you reboot due to a new kernel, you should again Check for updates, as there may be another major version available. Major version change in this context means 3.1.0 to 3.2.0 or 3.1.0 to 4.0.0. Patch updates mean 3.1.0 to 3.1.1. You will always be updated to the latest patch version when upgrading to a new version. If you are on version 3.1.0 and the following versions are available:

  • 3.1.0

  • 3.1.1

  • 3.2.0

  • 3.2.1

  • 3.2.2

  • 4.0.0

You will first be prompted that the 3.1.1 patch updates are available. Then you will be informed that a new version 3.2.2 is available. If you upgrade to the latest and run Check for updates again, you will be informed that a new version 4.0.0 is available. You may at that point confirm the upgrade to proceed to that version. If you run Check for updates again, you will be informed that there are no new updates available. At this point you know you have the most up to date system.

Updating the provider Configuration

After an update you need to visit the administrative section of your provider installation, to apply any missing or changed configurations.