Overview

The revenue eXtraction gateway (rXg) is RG Nets' next-generation IP data and voice revenue generating network gateway, combining the latest technologies to maximize operator profitability and minimize cost. This operation manual describes how to use the features and functionality present on each corresponding view of the rXg administrative console.

This operation manual assumes that the rXg device has been properly installed by a certified technician or qualified engineer associated with an entity that has a current RG Nets operator support agreement. Before continuing to use this manual on a newly installed rXg, please review the rXg installation and initial configuration guide. You can always find the latest version of the rXg quick start guide in the FAQ section of the RG Nets customer portal. Once you have gone through the rXg installation process, you will have the URL and access credentials for the RG Nets customer portal.

The primary mechanism used to navigate within the rXg administrative console is the menu at the top of each page. The menu is present at the top of all views of the console and allows quick access to all functionality.

Each of the buttons of the main menu represents a subsystem of the rXg. The primary link on each button leads to a dashboard of that subsystem. The menu text of the primary button becomes red to indicate which subsystem is currently being viewed.

Bringing the mouse pointer over a primary menu button and holding it there will reveal a sub-menu for each section. The links in the sub-menu bring up views to configure the various aspects of the subsystem. Once again, red indicates the subsystem that is currently being displayed.

A side panel menu can be accessed by clicking the arrow icon to the left of the screen. This side panel menu contains a history of the 4 most recently visited pages, as well as context-sensitive links to related configuration and informational pages.

Data Display, Sorting and Searching

Operator manipulation of data in the rXg administrative console is accomplished through AJAX enabled scaffolds. Each view consists of one or more scaffolds for various data aspects that can be manipulated to configure the subsystem.

Scaffolds display pertinent properties directly in the list view. Each of the column headers may be clicked to sort the data. Clicking the same column header again toggles the sort between ascending and descending. For example, if the first field header is clicked on the Accounts scaffold, the records are sorted by login.

Clicking on the login field header again reverses the sort. The data is now presented as a descending list.

Similarly, clicking on the third field header twice changes the sort to be descending by time.

Scaffolds containing a large number of records are automatically paginated. Navigation through the pages is accomplished through a set of links on the lower right corner of the scaffold. If the scaffold does not contain enough records for pagination, the pagination controls will not be displayed.

The previous and next links move backward and forward through the pages of records. The numbers enable quick access to a specific page.

The search link displays a form that enables the list display to be limited to items that match the data entered into the search field.

This is extremely useful when looking for a particular record in a scaffold that has a large data-set. In the example below, entering "baker" into the search field reduces the dataset from 94 to 2.

Clicking on the show link at the right of each record displays all of the detailed information available for that record.

Screen space limitations dictate that a reduced set of fields be present in the list view. Using the show link gives access to the other fields stored in the record. In addition to payload fields, meta-data fields such as the create and last update time, as well as the creator's administrative login and last updater may be seen in the detailed display.

Some scaffolds have additional per-record display capabilities. These can be accessed by using the additional links displayed at the right side of the list view. For example, several scaffolds can display per-record graphs.

To close a show, graph, help or other detailed display drop down, click on the white X in the red box at the top right of the detailed display area.

Data Entry and Export

The create new link found at the upper right is used to add data to the scaffold. Some scaffolds, such as those found in instruments , do not have a create new link because data cannot be directly added to the scaffold. When the create new link is clicked, a drop down appears with the fillable form elements available when creating a new record.

A new record is created immediately upon clicking the create button. If any errors are detected during the record creation, they are displayed inline in the form. The original data entered is preserved. Simply change the data to conform to the requirements and hit create to try to create the record again.

The export link allows the operator to download the data in the scaffold as a separated value text format. By clicking the export link, a drop down will appear that enables the configuration of the download. By default, the export mechanism will download all data in the scaffold with headers in a comma separated value (CSV) format.

Once downloaded, the data can be imported into a broad spectrum of software. For example, Microsoft Excel can import the data to create graphs and Crystal Reports can import the data for customized report generation.

System

The operator must configure and maintain several aspects of the rXg in order to properly deploy and operate an rXg powered revenue generating network. The rXg requires the operator to create an administrator , install an SSL certificate signed by a trusted third-party, and configure the appropriate time zone and time server options before an RGN may be brought into production. These prerequisites, as well as many other global configuration settings, are configured via the views of the System menu.

System Dashboard

The System dashboard presents an overview of options and configuration settings governing the global behavior of the rXg.

At the top of the system dashboard are graphs depicting CPU and Memory usage over the last 12 hours.

At the bottom left of the System dashboard is a dialog that presents currently utilized and maximum values for both transient and configuration license parameters.

Click on the details link to navigate to the License view of the administrative console to update the license key. Further information about the purpose and restriction of the parameters listed may be found on the manual page for the License view.

Click on the details link of either dialog to go to the options view of the administrative console where device and network options may be changed. Further information about the function of each option may be found on the manual page for the Options view.

At the bottom center of the system dashboard is a dialog that allows the administrator to view the status of the routine backup mechanism, and download the most recent backup of the rXg.

To back up the configuration, simply click on the download link. When clicked, the button will start a download process, resulting in the web browser prompting a download destination for the configuration to the administrator's computer. Save the backup file in a secure location, as the file may contain sensitive information about the end-users of the network that the rXg manages.

At the bottom right of the system dashboard is a dialog that allows the administrator to reboot , shutdown , and reset the rXg.

To prevent accidental shutdown , reboot , or factory reset , a dialog box will pop-up when any of the buttons is pressed asking for a confirmation.

The reboot option will cause the rXg to power cycle. This is useful if the rXg is behaving erratically after an abnormal condition such as overflow of the persistent storage device.

The shutdown option performs a clean power down of the rXg. Using this option is extremely important before disconnecting the power cord to ensure integrity of data.

The factory reset option erases the configuration data stored on the rXg and brings it back to factory defaults. Extreme caution should be used as a factory reset is a destructive and irreversible process. Important data such as the license key and SSL certificate for the rXg should be backed up before executing a factory reset.

Admins

The rXg administrative console implements all five tenets of a trustworthy system. Three of the five tenets (authentication, authorization and non-repudiation) are controlled on this view.

L3 authentication is enabled through the admin ACLs scaffold. By default, no active records are present in the Admin ACLs scaffold. In this default configuration, all devices may access the web administrative console. When an active Admin ACL record is present, the web administrative console may only be accessed by devices specified in the record.

L5-L7 authentication and non-repudiation are enabled through the Administrators scaffold. Each person that is involved with the administration of the rXg must have an independent record in the Administrators scaffold. Using strong login and password credentials enforces authentication. Enforcing administrative protocol to maintain distinct records for each administrator, prohibiting shared role accounts, and prohibiting revelation of credentials between administrators ensures non-repudiation.

Authorization is enabled through the Administrative Roles scaffold. Each administrator belongs to a role, and each role is granted a specific level of access to a subsystem of the rXg administrative console. As with any secure communication mechanism, adherence to proper protocol is of paramount concern to maintaining security. In order to ensure trust, there is no substitute or alternative to creating an individual administrative account for each administrator and using the Administrative Roles scaffold to apply an appropriate policy.

The remaining tenets of information security (confidentiality and integrity) are ensured by the use of SSL to protect communication between the administrator and the rXg. The configuration of the SSL subsystem is on a different view.

Access

The rXg web administrative console supports two access work flows: browser-based access and API-based access. Browser-based access is intended for human consumption and utilizes the login and password credentials configured when the administrator record is created. API-based access utilizes an rXg generated API key and is intended for computer consumption.

Browser-based Access for Human Consumption

Browser-based access is initiated when the operator wishes to access the web administrative console through a web browser to configure and instrument the rXg. To accomplish this, the operator uses a web browser to open the location https://rxg.dns.entry/admin/. If admin ACLs are in place, the device running the web browser must be listed in order to gain access to the admin login page. Credentials (as defined in the Administrators scaffold) must be specified to continue.

Once credentials are supplied, the web browser is automatically redirected to the Instruments dashboard. The operator may then use the web browser to access the administrative console according to the access restrictions defined by the administrative role that is associated with the administrator.

API-based Access for Computer Consumption

The rXg also supports direct API access to the console web application via HTTP. When an administrator record is created, the API key field is automatically populated with a random string. The operator must pass the generated value of the API key field, as a CGI parameter named api_key, to the console web applications controllers and actions.

One common use for API-based access is to perform automated backups from a third-party server or workstation. For example, an administrative workstation or server could be configured to periodically run the following command:

curl -O http://rxg.dns.entry/admin/menu/download_backup?api_key=fb9c5e...f6349

API-based access enables the operator to integrate simply with a broad spectrum of possibilities through standard HTTP. Nearly any task that is accomplished via browser-based access with a human present may be automated via API-based access. Some simple tasks are executed by hitting specialized actions with an HTTP GET such as the backup example described above. Most other tasks are executed through the RESTful API.

It is highly recommended that operators create specific accounts for API-based access rather than sharing an account between a human operator and computer automation. This enables the operator to quickly and easily discern between automated and manual requests through the admin log as well as helps keep the system more secure.

Administrators

The Administrators scaffold enables creation, modification, and deletion of accounts for administrators of the rXg.

To ensure authentication and non-repudiation of operator actions, each rXg administrator must have their own individual account protected by a set of strong credentials. Shared accounts and role accounts must be avoided as they represent a breach in security protocol.

The login and password fields are the credentials that identify an individual administrator. No administrators should be aware of the credentials of any other administrator. When creating a new administrator, the password must be entered twice for confirmation.

The service account checkbox, if selected, creates an admin that is used only to generate an API key and does not allow the service account to have access to the admin GUI.

The email field is used as the destination email address for system-generated email notifications. The selection of email notifications that the administrator will receive is governed by the notifications chosen in the administrative role that the administrator is associated with.

The role field defines an authorization policy for this administrator. The permissions for the roles in the list are defined by the Administrative Roles scaffold.

The first name , last name , and department fields are informational fields. They are only used in the Administrators scaffold to identify the administrator.

The public SSH key field is an optional field that the administrator uses to specify the credentials for secure FTP (SFTP) and command-line secure shell (SSH) access to the rXg. To enable SFTP/SSH access to the rXg, the administrator must generate a key pair using an SSH client and place the public key into the field. The key must be at least 4096-bit RSA or stronger. In addition, the administrator must be in an administrative role that has SSH access enabled.

Password authentication through SSH is not supported. Numerous resources are available for those that are unfamiliar withSSH public key authentication. In addition, a good book that covers this subject is SSH, The Secure Shell: The Definitive Guide (ISBN 0596008953) by Daniel J. Barrett, Richard E. Silverman and Robert G. Byrnes.

The API Key is an automatically generated string that is populated when an administrator record is created. The API key may be used by the operator to script operations by supplying the value as a CGI parameter named api_key to the administrative console web application. The value is determined by the rXg and is not editable through the create and edit actions.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Administrative Roles

The Administrative Roles scaffold enables creation, modification and deletion of authorization policies that govern authenticated administrators within the rXg administrative console.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The SSH checkbox authorizes secure FTP (SFTP) and command-line secure shell (SSH) access to the rXg. Valid public SSH keys must be present in the accounts of administrators for which SFTP/SSH access is desired.

The SMB checkbox authorizes Samba access to the rXg. Must be accompanied by an active SMB Server which contains to the policy or WAN targets which will be accessing the SMB Server.

The API checkbox authorizes access to the rXg admin web interface when providing a member Admin's API Key as the api_key_query parameter or the _apikey HTTP header.

The MFA Option specifies a Multi-Factor Authentication configuration to use for members of this Admin Role. When enabled, Admins must perform MFA when logging into the Admin console. Multi-Factor Authentication is configured in the Multi-Factor Authentication scaffold on this dashboard.

The MFA for SSH checkbox enables Multi-Factor Authentication for this role when logging in via SSH. Admins may perform public key authentication OR password + MFA authentication to access the SSH server. Fallback behavior in the event that the MFA provider is unreachable or has an invalid configuration is controlled within the associated Multi-Factor Authentication scaffold.

Each of the permission sets can be configured to be readwrite , readonly , or none. The readwrite setting allows full access. The readonly setting only allows administrators to view configuration for the section and disallows updates. The none setting does not allow any access to the section.

The master permission authorizes control over global hardware-specific configuration options. Licensing, SSL, configuration backup, and restore are governed by this permission.

The system permission authorizes control over core services and network configuration. Device options, IP addresses, routing, DNS, DHCP, and other configuration options that affect the rXg software as a whole are governed by this permission.

The identities permission authorizes control over configuration and options that affect the authentication of end-users. Management of end-user accounts, groups, definitions and applications are governed by this permission.

The policies permission authorizes control over configuration options that affect the end-user control and communication mechanisms. Configuration of the end-user experience via traffic shaping, HTML payload rewriting, content and packet filtering, etc. is governed by this permission.

The billing permission authorizes control over configuration options and log retrieval for the rXg accounting mechanisms. Management of access and usage plans, download quotas, recurring billing, and other accounting related activities are governed by this permission.

The instruments permission authorizes control over the viewing, manipulating, and downloading of real-time and archival data. Graphing, logs, and all other end-user cognizance mechanisms of the rXg are governed by this permission.

The various options in the notifications section determine which of the automatically generated emails the administrators who are a member of this administrative role receive. The rXg emails correspond to the custom messages configured via the email view of the Services menu.

The rXg emails are primarily used for event-driven notifications. For example, an administrative role for billing support personnel would want to receive failed transaction notifications. Similarly, an administrative role for network engineering would want to receive notifications for event triggers.

The Location Areas field is used to correlate this Admin Roles with that have APs with associated clients whose transactions will be discoverable for this Admin Role, so that Admins within this Admin Role may choose to approve those transactions.

Multi-Factor Authentication

The rXg supports verifying an administrator's identity by initiating Multi-Factor Authentication through a third-party provider. The Multi-Factor Authentication scaffold configures the rXg for multi-Factor Authentication.

The provider dropdown specifies the third-party MFA mechanism to be used for confirming administrator's identity.

The integration key , secret key , and API hostname fields should be completed using information from an application created within the provider's control panel.

The fallback mode determines the behavior that should be used when primary login is initiated, but the provider's service is unreachable or misconfigured. Completing Multi-Factor Authentication from the Admin UI requires that the administrator's device have Internet access, and in the case of SSH access, requires that the rXg have Internet access. If the rXg does not have Internet access, the fallback mode will be used to determine the login behavior.

When configured to allow access , errors with the configuration file or connection to the Duo service will allow SSH login without Multi-Factor Authentication.

When configured to prevent access , errors with the configuration file or connection to the Duo service will deny SSH access. This option is more secure but may result in you being locked out of SSH access to the system, and should be used with caution.

The admin roles selection determines which roles will trigger Multi-Factor Authentication after completing primary authentication.

Multi-Factor Authentication may be enabled for SSH access by enabling the MFA for SSH checkbox when editing an individual admin role. When MFA is used with SSH, the administrator may continue using a public key, if configured, but will fall back to username and password authentication with a Multi-Factor Authentication prompt before completion.

Duo Multi-Factor Authentication

In order to set up Duo Multi-Factor Authentication with the rXg, you will need to login to your Duo account, or create a new account at https://duo.com/

Once you are logged into the admin panel (https://admin.duosecurity.com/), you will need create a new Application to protect, and retrieve your integration key, secret key, and API hostname to be entered into the corresponding fields in the rXg.

To do so, click on the applications link on the Duo Dashboard, and then on "Protect an Application".

Next, search for the term "SDK" and click the protect button for the web SDK Application.

Copy the fields in the application details to the appropriate fields in the rXg

Select the admin roles for which Multi-Factor Authentication should be enforced.

Multi-Factor Authentication may optionally be applied to SSH access. If MFA for SSH is enabled in the admin role, the admin may log into the rXg via SSH by providing a public key OR providing a valid username and password combination. When providing a username and password, a push notification will be sent to the mobile device, or the admin may register by visiting a generated URL (if the Duo application policy allows it).

To configure Duo for SSH navigate to System::Admins and edit the administrative role for which you would like to enable MFA for SSH.

Single Sign-On Strategies

The Single Sign-On scaffold enables use of a centralized identity management store for administrative accounts of the rXg.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The role attribute field tells the rXg what user attribute to observe for an admin role assignment. An attribute value received which matches the name of an admin role will apply that admin role to the user.

The admin role dropdown enables the operator to select a fallback admin role. If the role attribute value is blank, or cannot be interpreted, the fallback role is used.

The provider dropdown selects the type of SSO application

The ID and key fields are used to authenticate to a specific application.

The scope field overrides default permissions requested by the app. Entries in the scope field may require an app review.

The alternate redirect hostname enables the operator to override the redirect URL to utilize a different FQDN than is configured on the rXg. This requires a DNS record pointing to the node and should fall under an existing wildcard certificate.

The button text field allows the operator to override the default text displayed within the button on the administrative portal login screen.

The IdP metadata URL (Identity Provider) can be used to import the SSO URL and certificate fingerprint of the remote identity provider. If the IdP provides this URL, the rXg will try to import the remaining fields.

The IdP SSO URL is provided by the identity provider as the URL to redirect logon requests to.

The IdP SLO URL is optionally provided by the identity provider as a URL to redirect log-off requests to.

The IdP cert fingerprint enables the operator to provide a SHA1 fingerprint of the identity providers certificate, for validation. Leaving this field blank disables certificate validation.

The SP EntityID (Service Provider) field enables an operator to override the default EntityID of the rXg. The default value is the active FQDN defined under System::Options::Device Options.

SMB Servers

The SMB Servers scaffold configures the rXg integrated SMB file sharing server. The rXg exposes several aspects of the onboard filesystem as SMB shares including, but not limited to, the portals, logs, backups, and TFTP datastores.

The rXg SMB share is accessible via the UNC \ip.address.of.rxg\datastore. For example, if the rXg IP address is 192.168.5.1 and the operator desires to modify the captive portal, the appropriate UNC is \192.168.5.1\portals. Datastores are appropriately flagged as read-only or read-write depending on their nature. For example, logs and backups are read-only whereas the portals and TFTP datastores are writable. The following named shares are available: admin login - the admin's home directory; "backups" - routine backups (read only); "logs" - raw log files (read only); "portals" - custom portals (read/write); "tftp" - TFTP boot directory (read/write);

The active field enables an option set. Exactly one option set may be active at any time. Enabling a particular option set will automatically disable another existing active option set.

IP layer access control to the SMB file sharing mechanism is controlled by the policy and WAN target fields. LAN access to the SMB shares must be initiated from an IP address that is a member of a group listed in the policy linked to the SMB server. WAN access must be initiated from an IP address that is listed in a linked WAN target.

User layer access control is configured via the administrator accounts configured on the system. The operator must supply a valid administrator account login and password that is linked to an administrative role with SMB enabled in order to access the SMB file shares.

Admin ACLs

The Admin ACLs scaffold enables operators to configure L3 access restrictions to the web administrative console. Since L3 ACLs take effect before L5-L7 credentials may be presented, the Admin ACLs are typically used to restrict access to the web admin console to a set of known devices. This helps thwart dictionary attacks against the L5-L7 authentication mechanism of the web administrative console.

The active field enables an option set. Exactly one option set may be active at any time. Enabling a particular option set will automatically disable another existing active option set.

The WAN targets and policies fields specify which sets of hosts should be allowed access to the web administrative console. By default, all devices are allowed access to the web administrative console. When an active record in the web admin console ACLs exists, then access to the web administrative console is restricted on L3 to the specified hosts.

It is extremely important to be careful when creating a web admin console ACL. Incorrect data entry may disable administrative access and may be unrecoverable. Once an admin ACL is active, the operator must specifically list hosts to be granted access on the WAN by creating WAN targets and enabling the appropriate check boxes. Hosts on the LAN may be granted access by placing the hosts into a group and then linking them into a policy selected here.

RADIUS Realms

The read role from class field allows you to override the selected default Administrative Role.

The administrative role drop down box allows you to specify the default administrative role for admins tied to the Radius Realm. For example, if an admin logs in and the read role from class box is unchecked, all admins will be tied to the role specified here; if read role from class is checked but the role doesn't match, the role specified in administrative role will be applied.

The encoding drop down lets the operator specify between PAP , CHAP , and MSCHAP.

The servers field allows you to specify the Radius Realm Servers the realm(s) authenticates against.

Using the Request Attribute settings, the operator can specify which attributes will be sent to the Radius Server.

Send NAS-IP-Address attribute indicates the identifying IP Address of the NAS which is requesting authentication of the user. This can be set to use Uplink IP of the rXg, or it can be specified using the NAS-IP-Address field.

The operator can Send Called-Station-ID , this can be set to use the uplink MAC or the operator can specify using the Called-Station-Id field.

The operator can send a NAS-Identifier. If the use domain name box is checked it will send the active Device Option's domain name as NAS-Identifier , or the operator can manually set a static NAS-Identifier using the NAS-Identifier field.

The operator can send the NAS-Port. If Use client VLAN is checked, the VLAN tag of the client will be sent as NAS-Port, or 1 if untagged. The NAS-Port field will manually set static NAS-Port.

When Send NAS-Port-Type is checked, the operator can specify the type by using the NAS-Port-Type dropdown and selecting from the list.

When Send requesting node IP is checked, requesting node IP attribute can be selected from the drop-down box.

When Send requesting node MAC is checked, the requesting node MAC attribute will be sent and can be selected from the drop down box.

RADIUS Servers

The priority field dictates the order servers are tried, where highest is first.

The host field is the RADIUS service IP address or domain name.

The secret field is the RADIUS shared secret.

The port field is the RADIUS service port (Default 1812).

The accounting port field is the RADIUS Accounting service port (Default 1813).

The tries field is the number of failed tries before moving on to the next least priority server.

The timeout field is the number of seconds per try to wait for a response from the server.

The realms field lets the operator select which Realms will be tied to the RADIUS Server.

TACACS+ is a security application that provides centralized validation of users attempting to gain access to a router or network access server. TACACS+ services are maintained in a database on a TACACS+ daemon running, typically, on a UNIX or Windows NT workstation. You must have access to and must configure a TACACS+ server before the configured TACACS+ features on your network access server are available.

TACACS+ Realms

The service name field is used to specify the custom TACACS+ service name.

The role attribute field is used to specify the custom TACACS+ authorization attribute to map to an administravite role name.

The administravite role drop down box allows the operator to specify the fallback role when the server does not provide the name of an existing role.

The operator can specify the TACACS+ servers to use the TACACS+ Realm by selecting servers in the servers field.

TACACS+ Servers

The priority field dictates the order servers are tried, where highest is first.

The host field is the TACACS+ service IP address or domain name.

The port field is the TACACS+ service port (Default 49).

The encoding drop down lets the operator specify between PAP, CHAP, and MSCHAP.

The secret field is the TACACS+ shared secret.

The tries field is the number of failed tries before moving on to the next least priority server.

The timeout field is the number of seconds per try to wait for a response from the server.

The realms field lets the operator select which Realms will be tied to the TACACS+ Server.

Backup

The Backup view presents the dialogs and scaffolds associated with creating backups, automated push-based remote backups, and restoring backups of the rXg.

Backup is a critical aspect of network continuity. Proper backups enable the RGN operator to quickly and easily recover from a rXg hardware failure. In addition, the rXg backup and restore mechanism enables operators to quickly replicate a rXg configuration across a fleet of rXgs.

The rXg supports operator initiated on-demand backups as well as rXg initiated periodic scheduled backups. On-demand backups are initiated via a dialog presented on the Backup view. Periodic backups are configured via the Routine Backups and Backup Servers scaffolds.

On-demand and Pull Backup

The operator may initiate a backup at any time via a dialog present on the Backup view. Backups always include the configuration of the rXg. Backups may optionally include custom portals, graph databases, and/or historical data by selecting the appropriate checkbox.

The on-demand backup mechanism may also be used by an operator as part of a pull backup system. The most common use case for this is when an operator wishes to have a server periodically initiate a backup. For example, a UNIX server that has cron and curl might be configured with the following crontab:

30 4 * * * curl -O https://rxg.host/admin/menu/download_backup?api_key=a...123
30 5 * * * rm -f `ls -ot | head -10`

The value for the api_key parameter is obtained from the Admins view. It is highly recommended that the operator creates a specific account for the purpose of enabling pull-based backup on both the rXg and the backup server. There are two additional parameters that may also be present in the URL:portalsWhen set to 1, custom portals are included in the backuprrdsWhen set to 1, graph databases are included in the backupThe two parameters mirror the check box options that are present in the dialog box. The configuration of the rXg is always included in the backup. If the operator wishes to be explicit, the parameterconfig=1 may also be passed.

Scheduled and Push Backup

The rXg supports scheduled backups that are stored on the local persistent storage device, pushed to external servers, and other rXgs. Backup schedules are determined by routine backup records. External servers that will receive push-based backups are configured via backup server records.

Routine Backups

Entries in the Routine Backups scaffold configures the schedule according to which the rXg will perform automated system backups.

The frequency field specifies the execution frequency of the automatic backup defined by this record.

An rXg routine backup will be limited to the configuration of the system by default. Routine backups may include the installed custom portals , recorded graph databases , and recorded historical data by selecting the appropriate check boxes.

The number of backups to keep on the rXg configures the length of the FIFO storage queue. The rXg creates and stores new backups on the rXg persistent storage mechanism according to the schedule defined by this record. When the number of stored backups reaches the value specified in this field, the rXg deletes the oldest stored backup.

The backup servers field associates this routine backup record with a remote server to which the backup will be pushed. The specification of a backup server is optional. The default behavior when no backup server is specified is to store the backup file on the local persistent storage.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Backup Servers

Entries in the backup servers scaffold contain the configuration data needed to establish a file transfer to a remote server for the purpose of pushing a backup file created by a routine backup.

The protocol field specifies the application layer protocol that will be used to transport the file.

The host field specifies the DNS name or IP address of the server that will be the destination of the file transfer.

The username , password , and SSH private key fields contain the authentication credentials for the server specified in the host field. When the FTP protocol is selected, only the username and password fields are relevant. When the SFTP protocol is selected, the operator may choose to use either password or public-key based authentication. Public-key authentication is enabled by copying and pasting a key into the SSH private key field and entering the key passphrase into the password field.

The path field specifies the destination on the remote filesystem for the backup file that is being pushed. The location specified by the path field must exist or the routine backup will fail. If the path is left blank, the default path on the server will be used as the destination on for the backup file.

The port field specifies the TCP port that will be used when a connection is made by the rXg to the server specified by the host field. If the port is not specified, port 21 is used for FTP and 22 is used for SFTP.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Receiving Backups

A secondary warm spare rXg may be configured to receive push backups from a primary active rXg. This mechanism enables operators to rapidly recover from rXg hardware failures. If the primary active rXg hardware fails, the operator simply logs into the secondary warm spare rXg and initiates a restore. The secondary warm spare rXg will then immediately take over the operation of the primary active rXg. This mechanism is most often as a redundancy solution for rXg cluster controllers.

To configure an rXg to receive backups, create a backup server on the primary active rXg. Configure the following settings in the new backup server record:

ProtocolSFTPHostDNS entry of the secondary warm spare rXg.UsernamebackupSSH private keyThe SSH private key from the secondary warm spare (a 4096-bit RSA key or stronger is required).All other fields may be left as their default. The SSH private key for the secondary warm spare rXg may be found on a dialog in the Backup view.

The backup server must be associated with a routine backup record that defines the transmission frequency of backups from the primary active rXg to the secondary warm spare rXg. Backups from the primary active rXg are displayed in the restore dialog of the secondary warm spare rXg.

Restore

An rXg may be restored with a backup that is uploaded by the operator or that is chosen from one or more that are stored on the local persistent storage. A dialog on the Backup view is presented to accomplish this task.

To restore a backup that has been previously created via a pull mechanism, use the file chooser dialog to select a rXg backup file that is accessible via the administrator's workstation. To restore a backup that has been previously created via a local routing backup or remotely pushed to the rXg, select a backup from the drop down.

If no local routine backups or remotely pushed backups are present on the rXg persistent storage, then the option to select a file stored on the rXg will not appear.

When restoring a backup, it is important to note that the rXg will maintain the license that is present on the rXg. Furthermore, when a backup is restored to a rXg that does not have the same Ethernet interfaces, the restore mechanism enables the operator to reconfigure the interfaces before the rXg comes online. This behavior enables operators to use a single rXg to build a configuration template that may be replicated across a fleet of rXgs.

Keep in mind that the flexibility of the backup and restore mechanism must be used in a reasonable manner. In general, the backup and restore mechanism is designed for similar machines. Restoring a secondary warm spare rXg that has fewer capabilities than a failed primary active rXg will likely result in disastrous consequences.

Config Templates

Entries in the Config Templates scaffold provide the ability to configure the rXg with YAML configuration files.

You can either paste in your configuration template into the config field, or you can load one from either a local file with the upload file field or a remote file with the remote URL field. If the remote URL requires basic authentication, then use the username and password fields.

The apply template field applies the config template immediately after saving.

The recurring method field instructs the backend to regularly fetch the file at the remote URL and apply it on a schedule.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Configuration Syntax

The top-level YAML object must be a key-value store (also called a hash, map, or dictionary) or an array of key-value stores. There are two types of top-level keys in the YAML configuration template: model/scaffold keys and smart keys.

Model keys (or scaffold keys ) are entries in the YAML template which create/modify entries in the database. These keys are based on the underlying ActiveRecord models, or scaffolds. You may use the PascalCase or snake_case version of the scaffolds (e.g., AdminRole, admin_role, or admin_roles); however, the PascalCase version ensures you don't conflict with a smart key. Fields are always written in snake_case.

For example, to add an administrator:

Admin:
- login: my_admin
  password: 'testPassword1!'
  password_confirmation: 'testPassword1!'
  admin_role: Super User
  ssh_keypairs:
  - name: my_admin authorized public key
    public_key: 'ssh-rsa AAAA...Q=='
    authorized: true

If you wanted to edit an existing record, ensure that the lookup field is defined first. For example, to set the time zone:

DeviceOption:
- name: Default
  time_zone: America/Chicago

Smart keys are snake_case entries in the YAML template which, in addition to creating entries in the database, perform some other operations. An example of this is the license_key. It is not enough to just create the entry; the backend also needs to process the key so the licensing limitations are removed. Otherwise, (for example) if later in the config template, the operator tries to set the Uplink to 1Gbps, the licensing limitations would not allow this until the backend processed the new license key. To set the license_key in a config template:

license_key: |
  abcdQabcduUzuo5IxtjuDabcdx6zVfEgnjl30Q4lDiabcdpCYmNrQa5x
  ...
  xKdOy1PabcdHydNCvs5CU5JLRabcdn0yHZIpv6FvDxFdmku7XiDEGuI=

Advanced Usage

Top-Level Data Structure

If your top-level data structure is a hash, then you cannot replicate keys, or they will overwrite one-another. So, to organize your config template to support duplicate keys, you need to use an array as your top-level data structure:

# configure management network
- Address:
  - name: mgmt
    cidr: 10.0.0.1/24
- Vlan:
  - name: mgmt
    interface: igb3
    tag: 4
    addresses: mgmt

# configure onboarding network
- Address:
  - name: onboarding
    cidr: 172.16.0.1/23
- Vlan:
  - name: onboarding
    interface: igb3
    tag: 5
    addresses: onboarding

Nested Associations

Rather than creating associated records in their own keys, you can also nest the associations, like so:

Address:
- name: mgmt # configure management network
  cidr: 10.0.0.1/24
  create_dhcp_pool: true
  vlan:
    name: mgmt
    interface: igb3
    tag: 4
- name: onboarding # configure onboarding network
  cidr: 172.16.0.1/23
  create_dhcp_pool: true
  vlan:
    name: onboarding
    interface: igb3
    tag: 5

Notice that this pattern is more concise and readable, and naturally groups associated records together, without having to convert your top-level data structure into an array.

Custom Lookups and Mutating Records

Normally, the first key/value pair under a model key will be used to lookup the record. For example, to edit an admin's role, you can do this:

Admin:
- login: someuser
  admin_role: Super User

However, suppose you wanted to edit a user's login. Then you should use the special _lookup field:

Admin:
- _lookup:
    login: sumusr
  login: someuser

Only Update Existing Records

Typically, when a config template is run, the rXg will look up an existing record and modify it, or attempt to create a new record if there is no existing record.

Sometimes you may wish to only update an existing record if it is found and never create a new record. To do this, you may use the special _updatefield:

AccountGroup:
- name: test
  priority: 5
  _update: true
- name: test2
  priority: 7
  _update: true

The template above would look for existing account groups with the name "test" and "test2" and update their priorities as needed. If the groups do not already exist, they will not be created, and the template will fail and be rolled back.

Delete Existing Records

A config template that contains an _delete key can be used to delete an existing record. See the following example:

Admin:
- login: testadmin
  _delete: true

The template above would look for an existing administrator account with the name "testadmin" and delete the administrator if it does exist.

Association Lookups

When defining a nested association, normally you can just provide a string with a "natural key", which usually refers to the name field on the associated record. There are exceptions for models which don't have aname field, such as the Admin model, and for those we try to use the most sensible field (login in the case of theAdmin model). However, you can also provide a full record definition, for which the normal rules apply (first key/value pair will be used for lookup), and you can even provide a nested custom _lookupfield. If the record doesn't exist, it will be created, assuming you provided all the required fields.

Supported Model/Scaffold Keys

We are not going to enumerate the model keys, since they map directly to scaffolds. You can refer to the rXg API documentation, or you can SSH into the rXg and run console to inspect the various models.

ActiveRecord models should generally be referenced using theirPascalCase name, to ensure you are not accidentally using a smart key. However, to accommodate flexibility, you may also use thesnake_case version of the model name in your config template.

Supported Smart Keys

license_key Configure the system with the provided license key. This key only takes a single string as an argument, but you do need to use YAML formatting to send multiple lines. For example:

license_key: |
  abcdQabcduUzuo5IxtjuDabcdx6gnjl30Q4lDiabcdpCYbK4VmNrQa5x
  ...
  xKdOy1PabcdHydNCvs5CU5JLRabcdn0yHZIpv6FvDxFdmku7XiDEGuI=

Use Config Template to Bootstrap New rXg Installation

A new rXg installation (before the first admin is created and the license is applied) can be bootstrapped and pre-configured using a configuration template delivered to the rXg in one of the two following ways: (a) on a USB drive during the initial rXg boot, or (b) via HTTP(S) download from a server advertised during the DHCP exchange.

The bootstrap process is executed after the installation of the rXg completes but before the first admin account is created and the license is added to the system.

The config template can be of arbitrary complexity and contain all the necessary baseline configuration elements, including local user accounts (administration, read-only, etc.), IP addressing, VLANs, IP groups, policies, etc., as long as the config template syntax is correct. It is also possible to include the license key in the bootstrap config template.

It is recommended that the bootstrap config template be vetted thoroughly before it is applied to any newly installed rXg systems to avoid misconfiguration and the need for additional cleanup.

Bootstrap via USB Drive

After the completion of the installation process, power down the rXg system, and insert a USB drive containing a config template file meeting the following conditions: (a) has an arbitrary name and .yml extension, and/or (b) contains the word template in the file name.

Power on the rXg system and during the boot process, the rXg performs a scan of any attached USB drives for potential config template files meeting the criteria listed before and applies them automatically, following the standard config template rules. If any errors are detected in the config template, the process will be interrupted and the config template will not be applied. The rXg in this case boots into the default state, with no admin user created and no license applied to the system.

Bootstrap via HTTP(S) Download

The HTTP(S) download bootstrap process involves specific DHCP server configuration and an HTTP(S) server on which the config template is stored.

The DHCP server provides an IP address to the rXg uplink interface during the boot process, following the standard DHCPv4 DORA process, as shown below, where the rXg acquires the uplink interface address. At this stage, the rXg does not request the DHCP bootstrap options. The example below shows the client rXg (rgxclient) be assigned the address of 192.168.151.182 from the DHCP server of 192.168.151.1. Only standard options are requested and provided.

19:02:00.139469 bc:24:11:02:b7:ae > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from bc:24:11:02:b7:ae, length 300, xid 0x15500df4, Flags [none] (0x0000)
        Client-Ethernet-Address bc:24:11:02:b7:ae
        Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Discover
            Requested-IP (50), length 4: 192.168.151.104
            Client-ID (61), length 7: ether bc:24:11:02:b7:ae
            Hostname (12), length 9: "rxgclient"
            Parameter-Request (55), length 10:
            Subnet-Mask (1), BR (28), Time-Zone (2), Classless-Static-Route (121)
            Default-Gateway (3), Domain-Name (15), Domain-Name-Server (6), Hostname (12)
            Unknown (119), MTU (26)
            END (255), length 0
            PAD (0), length 0, occurs 18
19:02:00.139571 3c:fd:fe:bd:a2:63 > bc:24:11:02:b7:ae, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
    192.168.151.1.67 > 192.168.151.182.68: [udp sum ok] BOOTP/DHCP, Reply, length 300, xid 0x15500df4, Flags [none] (0x0000)
        Your-IP 192.168.151.182
        Client-Ethernet-Address bc:24:11:02:b7:ae
        Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Offer
            Server-ID (54), length 4: 192.168.151.1
            Lease-Time (51), length 4: 3440
            Subnet-Mask (1), length 4: 255.255.255.0
            BR (28), length 4: 192.168.151.255
            Default-Gateway (3), length 4: 192.168.151.1
            Domain-Name-Server (6), length 4: 192.168.151.1
            END (255), length 0
            PAD (0), length 0, occurs 20
19:02:02.269492 bc:24:11:02:b7:ae > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from bc:24:11:02:b7:ae, length 300, xid 0x15500df4, Flags [none] (0x0000)
        Client-Ethernet-Address bc:24:11:02:b7:ae
        Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Request
            Server-ID (54), length 4: 192.168.151.1
            Requested-IP (50), length 4: 192.168.151.182
            Client-ID (61), length 7: ether bc:24:11:02:b7:ae
            Hostname (12), length 9: "rxgclient"
            Parameter-Request (55), length 10:
            Subnet-Mask (1), BR (28), Time-Zone (2), Classless-Static-Route (121)
            Default-Gateway (3), Domain-Name (15), Domain-Name-Server (6), Hostname (12)
            Unknown (119), MTU (26)
            END (255), length 0
            PAD (0), length 0, occurs 12
19:02:02.269596 3c:fd:fe:bd:a2:63 > bc:24:11:02:b7:ae, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
    192.168.151.1.67 > 192.168.151.182.68: [udp sum ok] BOOTP/DHCP, Reply, length 300, xid 0x15500df4, Flags [none] (0x0000)
        Your-IP 192.168.151.182
        Client-Ethernet-Address bc:24:11:02:b7:ae
        Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: ACK
            Server-ID (54), length 4: 192.168.151.1
            Lease-Time (51), length 4: 3438
            Subnet-Mask (1), length 4: 255.255.255.0
            BR (28), length 4: 192.168.151.255
            Default-Gateway (3), length 4: 192.168.151.1
            Domain-Name-Server (6), length 4: 192.168.151.1
            END (255), length 0
            PAD (0), length 0, occurs 20

Once the DHCP DORA is completed, the rXg periodically sends a DHCP Request message requesting Option 66 (bootfile-name) and Option 67 (tftp-server-name), as shown below. The DHCP server provides the requested Option 66 (config-template-mdu.yml) and Option 67 (http://192.168.151.10). The only two supported transport protocols are HTTP and HTTPS.

19:15:52.002351 bc:24:11:02:b7:ae > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from bc:24:11:02:b7:ae, length 300, xid 0x57663714, Flags [none] (0x0000)
          Client-Ethernet-Address bc:24:11:02:b7:ae
          Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: Request
            Requested-IP (50), length 4: 192.168.151.182
            Hostname (12), length 9: "rxgclient"
            Parameter-Request (55), length 9: 
              Subnet-Mask (1), BR (28), Time-Zone (2), Default-Gateway (3)
              Domain-Name (15), Domain-Name-Server (6), Hostname (12), BF (67)
              TFTP (66)
            Client-ID (61), length 7: ether bc:24:11:02:b7:ae
            END (255), length 0
            PAD (0), length 0, occurs 19
19:15:52.004756 3c:fd:fe:bd:a2:63 > bc:24:11:02:b7:ae, ethertype IPv4 (0x0800), length 370: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 356)
    192.168.151.1.67 > 192.168.151.182.68: [udp sum ok] BOOTP/DHCP, Reply, length 328, xid 0x57663714, Flags [none] (0x0000)
          Your-IP 192.168.151.182
          Client-Ethernet-Address bc:24:11:02:b7:ae
          Vendor-rfc1048 Extensions
            Magic Cookie 0x63825363
            DHCP-Message (53), length 1: ACK
            Server-ID (54), length 4: 192.168.151.1
            Lease-Time (51), length 4: 3600
            Subnet-Mask (1), length 4: 255.255.255.0
            BR (28), length 4: 192.168.151.255
            Default-Gateway (3), length 4: 192.168.151.1
            Domain-Name-Server (6), length 4: 192.168.151.1
            BF (67), length 23: "config-template-mdu.yml"
            TFTP (66), length 21: "http://192.168.151.10"
            END (255), length 0

Once the rXg is provided with the requested Option 66 and Option 67 values, the HTTP(S) GET request is transmitted to the indicated server hosting the indicated config template.

192.168.151.182 - - [19/Apr/2025:03:53:37 +0000] "GET /config-template-mdu.yml? HTTP/1.1" 200 12301 "-" "Ruby"

The following message is displayed on the console

Console output after bootstrap

DHCP Server Configuration

The DHCP server used to provide Option 66 and Option 67 may use any platform available to the operator. The following examples show the configuration of the necessary DHCP options using a standard rXg DHCP server and two of the predefined options. The Services::DHCP scaffolds are used in this example.

Create new DHCP option entries for Option 66 and Option 67 under the Services::DHCP::DHCP Options scaffold, as shown below and assign them respective names and values. In the example below, Option 66 is assigned the address of the HTTP server hosting the YML file (http://192.168.150.10), while Option 67 is assigned the file name (config-template-mdu.yml).

DHCP options

Next, create a new DHCP option group under the Services::DHCP::DHCP Option Groups scaffold, as shown below. This group will be tied back to the DHCP pool associated with the IP address group / VLAN on which the new rXg is being bootstrapped. Note that several global options were also selected, including:

Global default-lease-time
Global max-lease-time
Global min-lease-time
send the local gateway address as primary DNS server (recommended)

DHCP options group

Once created, the DHCP pool for the target VLAN contains an entry associating it with the specific newly created options group (VID-0151 in this case).

DHCP pool association

Similar configuration can be also reproduced using any existing DHCP server, though details are outside of the scope of this document.

Dynamic Option 67

The value of Option 67 can be also defined using a more comprehensive set of parameters, by sending an HTTP(S) GET request to a specific page on the target HTTP(S) server (/config_template_fetch in the example below) with a number of parameters, comprising tuples of {param_name}=%{value}%, where the param_name depends on the internal implementation of the example config_template_fetch script, and the value is shown in the table below.

{value}	Internal rXg variable	Meaning
iui	IUI	rXg sends its local IUI value
serial_number	SystemInfo.system_serial_number	rXg sends its serial number
version	RXG_BUILD	rXg sends its current build information (version)
hostname	DeviceOption.active.domain_name	rXg sends its domain name
ip	Uplink.primary_interface_stat_alias	rXg sends the local primary uplink interface IP address
base_mac	PhysicalInterface.base_mac	rXg sends the local primary uplink interface MAC address
timestamp	Time.now.to_i	rXg sends the current time when the request is being made

The decision on which of the supported parameters to include in the rXg HTTP(S) GET request is implementation-dependent.

The resulting value of Option 67 requesting the bootstrapped rXg to send to the remote HTTP(S) server would look as follows for IUI and IP address values. This scring can be further extended by adding new parameters and their respective values.

/config_template_fetch?rxg_iui=%iui%&rxg_ip=%ip%

This mechanism allows the remote HTTP(S) server to provide a custom YML config template file in the function of the parameters filled in by the bootstrapped rXg node, including issuing the license (based on the IUI value), generating system certificates (based on hostname value), setting the WAN interface and system options (based on hostname and ip values), etc. The content and the operation of the HTTP(S) server in this respect is implementation-dependent and outside of the scope of responsibility of the rXg system.

Bootstrap Example

For the purposes of the demonstration of the bootstrapping process via DHCP message exchange, a new rXg system was installed and offered a MDU-like config template, enhanced with license information and the initial administration account.

console-initialization

Once the initialization process was completed, the UI displayed (provided that a valid license was installed within the template or already present in the Asset Manager), the Config Templates scaffold shows the config template downloaded during the rXg initialization process. The template is automatically applied to the rXg system, creating the necessary user accounts

config-template-download-status

The following example shows the state of the rXg system after the DHCP-driven bootstrap process is completed and the system is fully configured with the MDU-style setup, covering VLANs, IP addresses, policies, accounts, etc., as shown in the following screenshots.

view-after-bootstrap-01 view-after-bootstrap-02 view-after-bootstrap-03 view-after-bootstrap-04 view-after-bootstrap-05 view-after-bootstrap-06 view-after-bootstrap-07 view-after-bootstrap-08 view-after-bootstrap-09

The example of the config template used for this sectio of the manual is available here: YML example

Integrating with Ansible

Ansible is an automation engine that can automate configuration management, deployment, and many other IT needs. Ansible relies on OpenSSH, making it very lightweight and secure. Furthermore, Ansible does not require any remote agent for configuration management. By utilizing the rXg config template mechanism, Ansible can automate tasks across many installations.

Procedure

Install Ansible on a host machine. See Installation Guide.
Create Hosts file "/etc/ansible/hosts"

Populate hosts file (here I create a group called lab, and add my host to it).

  lab:
      hosts:
              lab.rgnets.net:
          production:
            hosts:
              production.rgnets.net:

Ad-Hoc Ping all hosts

  ndk@MBP ansible % ansible all -m ping
          [WARNING]: Platform freebsd on host production.rgnets.com is using the discovered Python interpreter at
          /usr/local/bin/python3.7, but future installation of another Python interpreter could change this. See
          https://docs.ansible.com/ansible/2.9/reference_appendices/interpreter_discovery.html for more information. **production.rgnets.com | SUCCESS =\> {**"ansible_facts": {
                  "discovered_interpreter_python": "/usr/local/bin/python3.7"
              },
              "changed": false,
              "ping": "pong"
          }
          [WARNING]: Platform freebsd on host lab.rgnets.com is using the discovered Python interpreter at
          /usr/local/bin/python3.7, but future installation of another Python interpreter could change this. See
          https://docs.ansible.com/ansible/2.9/reference_appendices/interpreter_discovery.html for more information. **lab.rgnets.com | SUCCESS =\> {**"ansible_facts": {
                  "discovered_interpreter_python": "/usr/local/bin/python3.7"
              },
              "changed": false,
              "ping": "pong"
          }

Ad-Hoc Ping all hosts in 'lab' group

  ndk@MBP ansible % ansible lab -m ping
          [WARNING]: Platform freebsd on host lab.rgnets.com is using the discovered Python interpreter at
          /usr/local/bin/python3.7, but future installation of another Python interpreter could change this. See
          https://docs.ansible.com/ansible/2.9/reference_appendices/interpreter_discovery.html for more information. **lab.rgnets.com | SUCCESS =\> {**"ansible_facts": {
                  "discovered_interpreter_python": "/usr/local/bin/python3.7"
              },
              "changed": false,
              "ping": "pong"
          }

Ad-Hoc copy a file to all hosts in 'lab' group

  ansible lab -m copy -a "src=/etc/ansible/test.yaml dest=~/"

Create an Ansible "Playbook". In Ansible, a playbook is a list of "plays". Plays are a collection of Ansible modules, or tasks to execute against one or more remote machines. In this example, we will utilize two "plays": template which is used to copy a file from our Ansible host to the desired rXg, and shell to execute a command on the rXg.

Create a rXg config-template YAML. Example: admins.yaml

  Admin:
          - login: dgray
            first_name: Dorian
            last_name: Gray
            email: [email protected]
            crypted_password: "$2a$11$NRMhuglh/HgEvB3Um2skUe9Y/GP0jceg6hZRYDrbLufnO0Y2ZN4tO"
            admin_role: Super User

Create an Ansible "Playbook" YAML. Example: adminmgmt.yml

  ---
  - hosts: lab
    tasks:
    - name: Copy Admins YAML to host(s)
      template:
      src: /etc/ansible/admins.yaml
      dest: ~/admins.yaml
    - name: Apply the YAML as a config-Template
      shell: "/space/rxg/rxgd/bin/apply_template ~/admins.yaml"
      register: apply_template_output
    - debug:
        var: apply_template_output

Execute the Ansible Playbook:

  ndk@MBP ansible % ansible-playbook adminmgmt.yml

  PLAY [lab] ***************************************************************************************************************

  TASK [Gathering Facts] ***************************************************************************************************
  [WARNING]: Platform freebsd on host lab.rgnets.com is using the discovered Python interpreter at
  /usr/local/bin/python3.7, but future installation of another Python interpreter could change this. See
  https://docs.ansible.com/ansible/2.9/reference_appendices/interpreter_discovery.html for more information.
  ok: [lab.rgnets.com]

  TASK [Copy Admins YAML to host(s)] ***************************************************************************************
  ok: [lab.rgnets.com]

  TASK [Apply the YAML as a config-Template] *******************************************************************************
  changed: [lab.rgnets.com]

  TASK [debug] *************************************************************************************************************
  ok: [lab.rgnets.com] => {
      "apply_template_output": {
          "changed": true,
          "cmd": "/space/rxg/rxgd/bin/apply_template ~/admins.yaml",
          "delta": "0:00:07.626886",
          "end": "2020-04-01 12:04:32.647933",
          "failed": false,
          "rc": 0,
          "start": "2020-04-01 12:04:25.021047",
          "stderr": "/space/rxg/console/vendor/bundle/ruby/2.6/gems/activesupport-4.2.11.1/lib/active_support/core_ext/....
          "stderr_lines": [
              "/space/rxg/console/vendor/bundle/ruby/2.6/gems/activesupport-4.2.11.1/lib/active_support/core_ext/object....
              "Creating new ConfigTemplate with name Generated by ndk at Apr 1, 12:4 PM"
          ],
          "stdout": "INFO : Initiated Apr 1, 12:04 PM",
          "stdout_lines": [
              "INFO : Initiated Apr 1, 12:04 PM"
          ]
      }
  }

  PLAY RECAP ***************************************************************************************************************
  lab.rgnets.com : ok=4 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0

Certificates

The Certificates view enables the operator to manipulate the cryptographic keys that are used in conjunction with rXg services that employ public key cryptography.

Cryptography in the form of transport layer security via SSL and IPsec protocols is present in several rXg services to ensure the privacy and integrity of the data being transferred. The RADIUS server, IPsec VPN concatenator, and of course, the web multiplexer that serves the captive portal and administrative console all require asymmetric cryptographic keypairs. The creation, import, and export of keypairs is accomplished by manipulating the Certificates scaffold.

The rXg web multiplexer and RADIUS server employ transport layer security (TLS) in the form of the SSL protocol. The VPN concatenator conforms to the IPsec protocol. Both TLS and the IPsec protocol suites incorporate signed certificates as part of their trust mechanisms. The Certificate Signing Requests scaffold enables the operator to generate trusted third-party certification requests. A trusted third-party signature is required for the certificate used by the web multiplexer to serve a captive portal in a production environment.

Third-party Signatures

Operation of an rXg served captive portal requires at least one administrator to have working knowledge of public-key cryptography and TLS/SSL. In particular, an administrator must be familiar with the process of obtaining a signed SSL certificate. This process must be repeated periodically since signed SSL certificates have a limited life time.

There are many references available on the Internet that provide detailed information about howpublic-key cryptographyworks as well as specific information about thetransport layer security protocol. Practical Cryptography (ISBN 0471223573) by Niels Ferguson and Bruce Schneier provides an excellent overview of this subject. Network Security with OpenSSL (ISBN 059600270X) provides detailed step-by-step instructions on the process of generating certificate signing requests as well as obtaining and installing third-party signed certificates.

To obtain and install a signed SSL certificate for an rXg:

Choose a domain name for the rXg.
- Configure your DNS server to resolve the chosen domain to the WAN address of the rXg.
- Set the domain name in the Device Options scaffold.
Click on the create new action on the Certificate scaffold. A drop-down dialog will appear.
- Enter a name for the new key chain. A good choice for the name of the new key chain is the domain name that you have chosen.
- Leave all other fields blank (except note if you have a note). The rXg will automatically generate a private key.
- Click the create button.
Click on the create new action on the Certificate Signing Requests scaffold. A drop-down dialog will appear.
- Give the new CSR a name.
- Choose the certificate key chain that was created in the previous step.
- Completely fill out the form.
- Choose the appropriate option to generate a CSR for a trusted third-party to sign. Do not use the self-sign or local CA options as this will automatically create a certificate that is not automatically trusted by most browsers.
- Click the create button.
A CSR will now be shown in the Certificate Signing Requests scaffold. Send the CSR to a trusted third-party signer to obtain a signed certificate to load into the rXg.
- Copy the CSR out of the list or show view of the certificate signing requests field into the clipboard.
- Contact a trusted third-party SSL certificate signer such asGo Daddy. Paste the CSR from the clipboard into the appropriate form along with payment.
- If the signer gives a choice of formats, choose X509 PEM, Apache, mod_ssl, or OpenSSL, as the rXg SSL web multiplexer is compatible with all of the above formats.
- Contact your domain administrator to authorize certificate issuance by clicking on a URL in an email sent by the third-party signer.
- Open the signed certificate and intermediate certificate(s) using a text editor such as WordPad, TextEdit.app, or vi.
- Edit the key chain record in the Certificates scaffold. Copy and paste the certificates into the appropriate fields in the record.
- Enable the key chain by setting on the check box next to the active field and clicking the update button.
- Wait for the web server to restart. When the web server comes back up it will be using the signed certificate.

Local CA Signatures

The Certificate Signing Requests scaffold also enables the operator to sign certificates using the rXg integrated certificate authority. This feature is typically used in conjunction with the IPsec concatenator to issue client certificates for IPsec host-to-site connectivity with the rXg. The rXg integrated certificate authority may also be employed as a powerful revenue generation tool. Operators with wireless distribution and access networks that have open connectivity at locations with high transient traffic are particularly suited to using the integrated rXg local certificate authority as a revenue generation mechanism.

In a typical usage scenario, one or more usage plans are created with misc. items specifying an additional charge for a secure connection. The captive portal is then configured to create a new certificate linked to a local certificate authority when these plans are purchased. In addition, the portal creates a new certificate signing request that is set to automatically sign chain with the local certificate authority. The portal would then present the certificate for the local CA, as well as the private key and signed certificate from the newly created certificate. Thus, an operator can generate significant additional revenue without any intervention once the configuration of the rXg and portal is established.

To setup a local certificate authority and begin signing certificates , use the following procedure:

Click on the create new action on the Certificate Authorities scaffold. A drop-down dialog will appear.
- Give the new CA a name. Use a name that reflects the purpose of the CA, for example "CA for VPN."
- Fill out the C, ST, L, O, OU, CN, and email fields appropriately. The information listed here should reflect your actual organization. The information in the fields is meant to allow the recipient of the certificate a method to contact the owner and confirm validity of the key.
- Click the create button. You now have a local CA that may be used to sign certificates.
Click on the create new action on the Certificate Key Chains scaffold. A drop-down dialog will appear.
- Enter a name for the new key chain. A good choice for the name of the new key chain is the name of the device for which it will be issued (e.g., "VPN srv CKC", "VPN client CKC 1", etc.)
- Select the CA that we just created in the previous step, which is "CA for VPN" if you followed our example.
- The rXg automatically populates the server field.
- Leave the intermediate and certificate fields blank.
- Click the create button.
- Repeat the steps above. At least two key chains (one for the rXg and one for the client) are needed to support most applications such as the IPsec VPN.
Click on the create new action on the Certificate Signing Requests scaffold. A drop-down dialog will appear.
- Give the new CSR a name.
- Choose from one of the certificate key chains that were created in the previous step ("VPN src CKC" and "VPN client CKC 1" if you followed our example).
- Completely fill out the form.
- Choose the appropriate option to generate a CSR and sign with linked local Certificate Authority. The CA that was generated in the first step and linked in the second step will be used to sign the certificate.
- Click the create button.
- Repeat the steps above. At least two key chains (one for the rXg and one for the client) are needed to support most applications such as the IPsec VPN.
Export all of certificates that we have just created along with the private key for the client so that they may be loaded into the client software. Specifically, you need to copy and paste the following items into files that must be copied onto the client:
- The certificate field from "CA for VPN"
- The certificate field from "VPN src CKC"
- The certificate field from "VPN client CKC 1"
- The server field from "VPN client CKC 1"

The procedure for installation of certificates and private keys onto the client device is highly dependent upon the client device software. The vast majority of client software will have a certificate manager with specific keystores for CA certificates, regular certificates and private keys. For example:

In the client software shown above, the operator must combine the contents of the certificate and server fields from "VPN client CKC 1" into a single file before importing with the "PEM/DER encoded certificate with private key" option. This may be accomplished by copying and pasting both sets of data into a text editor and saving the file. The "VPN srv CKC" certificate must be imported using the "PEM/DER encoded certificate without private key" option. The "VPN CA" certificate must be imported with the "PEM/DER encoded CA certificate" option.

The rXg integrated certificate authority may be used to support an unlimited number of clients. The same procedure as described above (omitting step #1) is used to create certificates and keys for additional clients. Once the certificate authority is set up, automating the creation of certificates for clients is very easy. For example:

ca = CertificateAuthority.find_by_name('VPN CA')

ckc = SslKeyChain.new
ckc.certificate_authority = ca
cc.save!

csr = CertificateSigningRequests.new
csr.SslKeyChain = ckc
csr.country = 'US'
csr.state = 'NV'
csr.locale = 'Reno'
csr.organization_name = 'RG Nets'
csr.common_name = 'vpn.rgnets.com'
csr.email_address = '[email protected]'
csr.sign_mode = 'ca'
csr.save!

If the code above were to be included in a customized portal, the country, state, locale, organization, etc., should be changed to reflect the operator. The certificates that the end-user would need to install may be presented in a portal view using the Ruby code shown below: Server Certificate <%= SslKeyChain.find_by_name('VPN srv CKC').certificate %> CA Certificate <%= ca.certificate %> Client Certificate <%= ckc.certificate %> Client Private Key <%= ckc.server_key %> Integrating and fully automating the generation of client certificates is a simple way to provide an IPsec VPN premium service offering. The IPsec VPN offering may be marketed as a wireless security mechanism, a remote access mechanism, or both at the same time. See the IPsec documentation for more details.

Active Certificate

The Active Certificate dialog at the top of the Certificate view presents a scrollable view port that contains the certificate currently in use. The details of the certificate are presented in text format. The certificate itself, in PEM format, can be found by scrolling to the bottom of the view port.

Certificates

The Certificate Key Chains scaffold enables the operator to manage the public and private keys used to ensure privacy and integrity of communication between the administrator and the operator.

The active field enables an option set. Exactly one option set may be active at any time. Enabling a particular option set will automatically disable another existing active option set.

If no keychain is set active, the rXg uses a self-signed keychain for bootstrap purposes. The bootstrap keychain is completely unsuitable for production environments. The captive portal will behave erratically when used with the self-signed bootstrap keychain. Replace the bootstrap keychain with one that has a certificate signed by a reputable trusted third-party signer immediately.

The server key algorithm dictates what algorithm is used for the private key of the certificate. When creating a certificate for the purpose of OpenRoaming RadSec, the key algorithm must be secp384r1

The certificate authority field associates this record with a local certificate authority. This field is optional and should be left blank if a trusted third-party will be used to sign this certificate. When this field is set, the linked certificate authority will be used to sign the certificate chain if a certificate signing request is created with a request for a local signature.

The server field contains the private key part of the keychain. In most cases a new keychain is created when the operator expects the rXg to generate the key. In this case, please leave this field blank when creating a new keychain to have the rXg automatically generate a private key. When installing a chain that was generated and/or signed elsewhere, this field must be populated with the server private key in PEM format.

The intermediate field contains the certificate(s) issued to the trusted third-party signer by a trusted root certificate authority. In most cases, this field must be populated with an intermediate certificate that can be downloaded from the website of the trusted third-party signer.

The certificate field contains the certificate issued to the domain administrator by the trusted third-party signer. This field must be populated with a signed certificate before the certificate chain may be made active. If the operator generates a CSR with a local certificate authority signature, this field will be populated with the signed certificate automatically.

Certificate Signing Requests

The Certificate Signing Requests scaffold enables the administrator to generate X.509 public key signing requests for submission to trusted third-party signers.

The certificate field chooses a key pair for which to generate the certificate signing request.

The certificate identification fields are used to identify and describe the organization making the certificate signing request. It is extremely important to be very careful when entering the data in the following fields. If a trusted third-party signer is used to sign a certificate, it may choose to validate each of the fields with arbitrarily high precision. If a local CA is being created, the end-users who will load the CA cert may choose to verify the trustworthiness of the CA based on the data in these fields.

The country code field is the ISO 3166-1-alpha-2 country code of the requesting organization.

The state field is the state or province of the requesting organization.

The locality field is the city or town of the requesting organization.

The organization field is the company name of the requesting organization.

The organizational unit field is the section or division of the requesting organization.

The common name field is the fully qualified domain name of the rXg. This field must match what is set in the active device option.

The email address field is a contact email address for the requesting organization.

When creating a RadSec certificate for the purpose of WBA OpenRoaming, there are a few considerations that must be met:

The certificate's Server key algorithm must be secp384r1
The key usage must be set to client+server.
The Organizational Unit (OU) must be set to WBA:WRIX End-Entity
The UID should be set to the WBA member ID, e.g. MYCORP:US
The Policy identifier must be 1.3.6.1.4.1.14122.1.1.7

The sign mode field specifies how the operator intends to execute the signing for the CSR that is to be generated. The operator may choose to simply generate the certificate without any local signing. This is the option that should be used when the certificate will be signed by a trusted third-party. The operator may also choose to sign with a local certificate authority. This option is only valid if the certificate chain is associated with a local certificate authority. Finally, the operator may choose to self-sign the CSR. This option is for testing and demonstration purposes only and should never be used in a production environment.

The certbot credential is a necessary association if, and only if, a sign mode has been selected that requires a certbot credential.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Certificate Authorities

The Certificate Authorities scaffold enables the operator to create and manage local CAs that are used to sign certificate chains. The certificates that are signed by local certificate authorities take part in a chain of trust that begins with the CA certificate.

The country code field is the ISO 3166-1-alpha-2 country code of the requesting organization.

The state field is the state or province of the requesting organization.

The locality field is the city or town of the requesting organization.

The organization field is the company name of the requesting organization.

The organizational unit field is the section or division of the requesting organization.

The common name field is the fully qualified domain name of the rXg. This field must match what is set in the active device option.

The email address field is a contact email address for the requesting organization.

The days field specifies the number of days that a signature for a certificate will be valid for. An expired certificate must be resigned before it can be used.

The CA keypair are automatically generated when the operator creates a new record in this scaffold. The certificate and private key fields contain the two halves of the keychain and may be accessed via the show option once a record is created. The certificate is what needs to be distributed to clients that wish to verify the trustworthiness of certificates signed by this certificate authority. The private key should never be copied out of the rXg except for backup purposes or if the CA keychain is to be used on a third-party CA for signing certificates.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

EST Certificate Servers

Enrollment over Secure Transport (EST) is a certificate management protocol for PKI clients needing to acquire client and associated CA certificates. The EST Certificate Servers scaffold enables the operator to create and manage EST servers that are used to retrieve signed certificate chains and CAs.

The host field specifies the FQDN or IP address of the EST server.

The port field specifies the remote TCP port the EST server is listening on for incoming connections.

The certificate authority allows the operator to select which imported CA will be used as the explicit trust anchor.

The label field is optional and denotes the EST partition to interact with.

The client certificate drop-down can be used to select a certificate used for authentication against the EST server.

The username and password fields can be used for basic authentication against an EST server.

Certbot Credentials

The Certificate Credentials scaffold enables the administrator to define api_key/email/provider records for 3rd party ACME-enabled, and API Key-enabled Certificate Authorities.

The Email field defines the username for the API Key.

The API Key field defines the API Key shared secret.

The Provider field defines which provider this credential is meant to be used with.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Let's Encrypt Examples

This example will show the creation process to setup and retrieve a certificate to be used for the FQDN using Let's Encrypt. NOTE: The use of Let's Encrypt requires the Let's Encrypt servers to reach out to the system via the FQDN to make sure the requester owns the domain, if an ACL is in place this can prevent Let's Encrypt from retrieving the required information. An ACL will also prevent the certificates from being automatically renewed.

First navigate to Systems::Certificates.

Create a new Certificate.

For Let's Encrypt the top section can be ignored (shown below).

The Certificate signing request section needs to be completed. Give the record a name, this can be the FQDN but does not need to be. Leave the Usage field set to server. Change the Sign mode field to Generate CSR and obtain certificate from Let's Encrypt. Enter the FQDN into the Common Name (CN) field. Enter the 2 letter country code into the*Country Code (C)* field. Enter the state into the State (ST) field, this should be spelled out and not the 2 letter abbreviation. Enter the city into the Locality (L) field. The Orgainization (O) field is optional, along with the Organizational Unit (OU)field. Enter a valid email address into the Email address field, this should be an email specifcally for this and not a personal email address. Click Create , this will start the certificate retrieval process.

It will take a minute or two to retrieve the certificate, one retrieved it will display the following. If for some reason the certificate cannot be retrieved a health notice will be generated with information regarding why it failed, this is usually because the system cannot be reached, either because the FQDN does not resolve to the primary IP address of the system, or an ACL is in place.

The final step is to edit the record, check the active box and click Update. This makes the certificate active and now when you use the FQDN name to access the system it will be secure.

Let's Encrypt Certificates for Virtual HTTP Hosts

Generating a Let's Encrypt Certificate for use with HTTP Virtual Hosts follows the above example with the exception that the Active box is not checked after retrieving the certificate. The FQDN being used to access the HTTP Virtual Host must resolve to the primary IP address of the system.

Next the HTTP Virtual Host must be created by navigating to System::Portals.

Create a new HTTP Virtual Hosts.

Give the record a Name , this is arbitrary and does not affect how the HTTP Virtual Host performs. Enter the FQDN used in the certificate in the previous step in the Hostname for remote access. The Target server IP field is the private IP address of the device to be accessed via the FQDN. Enter the port the device is listening on in the Target listening port field. If the device is listening for HTTPS connections check the HTTPS box. Select the certificate created in the previous step in the Certificate field. Click Create.

Now the device can be accessed via the FQDN we configured in the virtual host. This allows the operator to access devices behind the rXg over a secure connection even if the device itself is not HTTPS. To access the device enter https://esxi.neurotic.ninja into the browser.

Cluster

The rXg clustering solution simplifies and unifies the management of large scale rXg deployments.

An rXg cluster controller centralizes the configuration, instrumentation, and all operationally relevant persistent storage of a cluster of rXg devices. Synchronized, parallel, highly available, and cost-effective operation of an rXg cluster is easily achieved, enabling clear communication, authoritative control, and complete cognizance over a diverse RGN end-user population.

Load Balancing, Scaling and Failover

In a typical clustered rXg deployment, the distribution network is divided into parallel segments that are configured to be independent collision domains for the purposes of load balancing. Each rXg cluster node is then assigned one or more LAN segments to manage. A single, unified identity management and policy enforcement configuration is then applied to the entire cluster. This enables a cluster of rXg devices to support networks of virtually unlimited scale.

An rXg cluster automatically provides a failover configuration. In the event of a node failure, L2s and L3s of the failed node are automatically moved to operational nodes. End-users experience no downtime, and the process requires no operator intervention.

Topology

The approved cluster deployment topology is creating a private network solely for the purpose of cluster internal communications. It is highly recommended that the physical layer of the cluster internal communications network be gigabit Ethernet. Cluster nodes must use a native port to communicate directly with the controller (not a VLAN trunk port). The cluster intercommunication network (CIN) may be provisioned via a VLAN switch if and only if the cluster nodes are connected via untagged ports. In general, an Ethernet interface that is associated with an uplink on the node or controller should never be used for the CIN. In theory, the cluster may be connected over the public Internet, however this configuration is not officially supported.

The segmentation of the distribution LAN is usually accomplished via a VLAN switch. The segment assigned to the rXg cluster nodes is usually accomplished via VLAN trunk ports in order to ease management. There is no fundamental issue with using native ports to achieve the same goal, though naturally the management of the additional physical cabling may be more cumbersome.

Configuration

By default, the rXg stores its configuration database locally on the same hardware that executes the administrative console, portal web application, and enforcement engine. The rXg can be configured as part of a cluster using the Cluster Node Bootstrap scaffold of the Cluster view.

When operating as a node of a cluster , the rXg shares a remote database with all of its peers. By sharing a single database between all nodes, the operator uses a single, unified console to configure settings that are global to the cluster (e.g., end-user identity management, policy enforcement, etc.) as well as unique to the individual node (e.g., networking, SSL certificates, etc.). In addition, instrumentation and logging from all nodes in the cluster is centrally stored in the same shared database that resides on the cluster controller. This enables the operator to obtain complete cognizance over any end-user that is on any node of the cluster through the cluster controller administrative console.

To enable an rXg as a cluster controller, the operator creates an entry in the Cluster Nodes scaffold. The first entry will always be for the master controller. Subsequent entries will be made for standby controllers , nodes , and witnesses. The operator will need to provide the IUI, IP address, and HA Role for each subsequent system.

Each cluster should only contain one master controller entry which will contain the read-write copy of the database.

Standby controllers can be defined to receive read-only copies of the database and have the ability to promote to master controller in the event of a failure.

Nodes contain no copy of the database and participate in the cluster by managing individual LAN segments.

A witness does not contain a local copy of the database or manage any LAN segments. The function of a witness is to maintain quorum in the event of a failure.

A cluster controller presents a Cluster Nodes scaffold on the Cluster view that configures the member nodes that are attached to the cluster controller. The operator must create a record for each and every cluster node that is to take part in a cluster managed by the cluster controller. Each record contains the credentials that authorize the cluster node to share the cluster controller database.

Deployment Procedure

A successful cluster deployment begins with a proper plan and documentation of the cluster topology. At very least, a network diagram must be created that has all relevant IP addresses labelled. Every cluster node must have at least three connections (LAN, WAN, CIN). The cluster controller must be connected to the CIN. The LAN and WAN connections are optional on the cluster controller , though recommended to ease remote and local access to the management console as well as enable ping targets for multiple uplink control.

Install the rXg cluster controller(s), and all rXg cluster node hardware according to RG Nets guidelines.
Power on the devices and connect to the administrative console of each device.
Use the WAN IP address to connect to the administrative console as all units will have the same default LAN IP address at this time. If necessary, connect a serial terminal or VGA monitor to the rXg and hit CTRL-D to see what WAN IP address the rXg has acquired.
Create at least one administrator and install a valid license on the master controller.
On the master controller , bring up the LAN view and create an Ethernet interface along with an associated network address. This will define the CIN and allow all nodes to communicate with one another once configured.
Bring up two web browsers side-by-side. In one browser, open the administrative console of the cluster controller and navigate to the cluster view. You should see the Cluster Nodes scaffold with a single entry (the cluster controller ). In the second browser, bring up the administrative console of a cluster node (still in default state) and you should see the Cluster Node Bootstrap scaffold. The master database should be currently set to local master.
Create a new Cluster Node scaffold entry on the master controller by copying the IUI of the second system and defining the IP Address. Use the dual browser setup to repeat the process outlined here for each node that will take part in this cluster.

A new record in the Cluster Nodes scaffold must be created for every rXg device that will participate in this cluster.

Copy the IUI from the browser displaying the cluster node console and paste it into the appropriate field displayed in the cluster node record creation form.
Enter the CIN IP address that will be configured on this node into the IP field.
Choose the appropriate mode for the rXg device. Use the dual browser setup to repeat the process outlined here for each node that will take part in this cluster.
Click the edit link next to the record in the Cluster Node Bootstrap scaffold in the administrative console of the node. Enter the CIN IP address of the cluster controller in the Controller IP field. The settings for the username and password fields are displayed in the list view of the Cluster Nodes scaffold on the administrative console of the master controller. Copy and paste those values into the appropriate fields.
Choose the CIN port for the interface setting and enter the CIN IP address in CIDR notation for the cluster node into the local IP address fields. Click update to save the settings.

When the cluster node connects to the remote database on the cluster controller for the first time, a cluster node initialization process is automatically executed. First, the cluster controller incorporates the MAC addresses and media-types available to the cluster node into the set of all available Ethernet ports. Then, records for the CIN Ethernet interface and address are added to the cluster configuration and marked for application to the particular cluster node that is being initialized. In addition, a default device option for the new cluster node is created.

When all cluster nodes have been initialized, the deployment of the cluster is complete. The operator can input licensing for each node in the License Keys scaffold in the Cluster view. The cluster may now be configured with settings in a similar manner as a standalone rXg, by using the master controller administrative console.

Symmetric Cluster

In a symmetric cluster a node can operate as both the data plane and control plane. Because each node requires large, high endurance SSDs as well as enough CPU and RAM to operate as both the control plane and data plane, symmetric clustering is recommended for smaller deployments.

Asymmetric Cluster

An asymmetric cluster separates the control plane from the data plane. This enables the operator to scale requirements for nodes individually. Only nodes allocated as controllers need large high endurance SSDs, more CPU, and RAM. Data plane nodes require minimal SSD, CPU, and RAM to manage their individual LAN Segments.

All transit networking features are executed on the cluster nodes. The controller does not forward packets nor does it run any proxies for web experience manipulation. All billing, user management, and instrument collection features are executed on the cluster controller. Cluster nodes do not run recurring billing, system status, or traffic rate collection tasks.

Implementation Details

The gateway setting in the Database Storage scaffold of cluster nodes should not be configured unless absolutely necessary. Setting this implies that the cluster node will connect to the cluster controller via an uplink interface and is not officially supported.

All CIN traffic is passed through the rXg policy enforcement engine unfettered. No packet filter states are created and traffic is not queued. Ensure proper cluster operation by making sure that the CIN is properly deployed using high performance gigabit Ethernet equipment and high-quality cables.

A valid license must be present in the license view of the cluster controller for every node associated with the cluster.

Device and network configurations are associated with a particular node while almost every other kind of configuration is global. If a scaffold does not have a field that associates a node with the record, the record will apply globally to the entire cluster. When the scaffold has an active setting, only one record per cluster node may be made active. The records that are not active are shared by the cluster.

When configuring Ethernet interfaces , one port will be available for each physical port in the cluster. Since all networking configuration (e.g., addresses , uplinks , VLANs , binats and even all the DHCP server settings) are ultimately linked to an Ethernet interface , the port field determines which node the configuration applies to.

A single uplink control record may contain uplinks that span several nodes of the cluster. However, on each node, only the relevant uplinks are used to determine the weighted connection pools.

Ping targets may be configured as node-specific (associated with a cluster node record). Ping targets that are node-specific are pinged and status-updated by their associated node only.

Ping targets that have no cluster_node association are global to the cluster. Global ping targets are status-updated by only the cluster controller. However, global ping targets may and should be used to instrument the condition of multiple uplinks configured throughout devices in the cluster. In this case, all nodes having an uplink associated with the global ping targets ping the target through the respective uplink(s), but only the online state of the uplink record is changed, not the state of the global ping target itself, except by the controller. Creating a ping target with an uplink(s) association automatically clears any cluster node associated with it.

System graphs must be cluster node specific and represent data for only that node or the cluster controller.

Network graphs are global. Graphs of IPs , MACs , login sessions , bandwidth queues , and policies represent cluster-wide data. For example, traffic rate stats for the same IP that may somehow be behind two different nodes is accumulated at the controller and collated into a single database entry for that IP. Similarly, traffic rates statistics for a single bandwidth queue or policy are collected from all nodes, summed at the controller, and written to a single database entry. Cluster node specific items defined by the records that are directly or indirectly associated with an Ethernet interface record are stored in node specific records.

Cluster Node Bootstrap

The Cluster Node Bootstrap scaffold configures the mechanism by which this rXg will join a cluster.

The controller IP field specifies the IP address of the rXg cluster controller.

The username and password fields are the credentials assigned to this node by the cluster controller. Obtain the values for these fields by entering the IUI for this node into the Cluster Nodes scaffold of the Cluster view on the console of the cluster controller.

The interface field configures the Ethernet interface that will be used by this cluster node to communicate with the cluster controller. An Ethernet interface must be dedicated for the sole purpose of cluster communications.

The local bootstrap configuration options ( local IP address and gateway ) are used as the bootstrap configuration of the rXg when operated in cluster mode. This is needed to enable the cluster node to communicate with the cluster controller and retrieve the complete rXg configuration from the controller.

Cluster Nodes

Cluster nodes define the members of an rXg cluster.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The auto registration box enables automatic registration of cluster nodes. Allows for automatic cluster configuration.

The permit new nodes box allows new nodes that have never been a member of the cluster to join the cluster.

The auto approve new nodes box allows new nodes to be automatically approved without operator intervention.

The pending auto registration box, if checked, will mark the node as pending auto registration. When the node connects to the master controller for the first time it will automatically become a member of the cluster.

The mode dropdown indicates the type of node defined by this record. Only one node may be defined as the master controller for each cluster.

The IUI is the installation unique identifier for the node that is defined by this record. The installation unique identifier for an rXg may be found by visiting the license view of the system menu.

The IP is the IP address that will be used by the cluster node for communicating with the cluster controller. This will also be the bootstrap IP address that is configured in the Database Storage scaffold of the Cluster view on the cluster node.

The priority field indicates the priority of an individual node. A higher precedence node takes over for lower precedence gimps within the same team.

The networking HA enabled field defines the HA behavior of this node in the cluster; if checked this node will take over networking for a failed node, if unchecked the node will not.

The networking HA backoff (seconds) field specifies the amount of time a node will try to reach the controller before moving on to the next controller. Default value is 300 seconds.

The networking HA timeout (seconds) field specifies the amount of time that must elapse before a node is considered offline, and another node will take over the networking configured on the failed node. Default value is 300 seconds.

The username and password fields are the credentials assigned to this node by the cluster controller. Enter these into the cluster view of the appropriate cluster node to enable access.

Example Cluster Setup: 2 CC's, 2 GW's

For this example, there will be 4 machines: 2 CC's and 2 GW's. For different cluster layouts there may be more CC's or GW's. The example below will provide details on adding each type. The first step will be to install the rXg software on all 4 machines. Once this is done, two browser windows should be opened: one for the primary CC, and the 2nd for all additional nodes (this includes any CC's or GW's that will be added).

Create a new administrator on the Master Controller , by clicking "Create New" on the Administrators scaffold. Each admin account should be unique for every operator.

At a minimum a Login and Password are required. Click create.

Next edit the License Keys scaffold.

Paste in the license key and click update. This will restart the webserver.

Next the CIN (Cluster Interconnect Network) will be created. Navigate to Network::LAN , and create a new network address.

Name: cc1 CIN Address. Set the interface , and specify the IP address in CIDR notation. Leave both autoincrement and span values at 1. Do not check create DHCP pool. Click create.

Turn rXg into Master Controller by navigating to System::Cluster. Create a new cluster node by clicking create new on the Cluster Node scaffold.

Uncheck networking HA enabled this will ensure that the CC doesn't take over the networking for the other nodes before they are integrated into the cluster. Verify that the default information is correct and click create.

Create a new cluster node record for each CC and GW that will be added to the cluster. The easiest way to do this is to have 2 browser windows open, one with the Master Controller admin GUI loaded, and the other with the admin GUI with a tab for each CC and GW. Click create new on the Cluster Nodes scaffold.

Verify the name and mode is correct. Copy the IUI from the secondary controller into the IUI field on the Master Controller , verify that the mode , IP , and priority are configured as desired. Uncheck the networking HA enabled box. Click create.

Next repeat for the 2 GW nodes. Click create new on the Cluster Nodes scaffold, copy the IUI from the first GW node into the IUI field. Verify that the mode , IP , and priority are configured as desired. Uncheck the networking HA enabled box. Click create.

Repeat for GW 2. Verify that the mode , IP , and priority are configured as desired. Uncheck the networking HA enabled box. Click create.

All the CC's and GW's now have cluster node records on the Master Controller.

Next, we will integrate the secondary CC and GW's into the cluster using the Cluster Node Bootstrap scaffold. On the secondary cc admin GUI in the second browser edit the cluster node bootstrap record.

Copy controller IP , username , password from the Master Controller's Cluster Nodes scaffold to the secondary controller. Set the interface , and the local IP address in CIDR notation. Click update.

Repeat the process for GW 1 and GW 2 nodes.

Next add the license for each node. On the Master Controller edit the license key entry for cc2 paste the license in. Repeat for each node.

After the licenses have been installed on the remaining nodes the cluster configuration is complete. The operator will now use the Master Controller to continue configuring the system. The System::Cluster page will now show Replication and HA status as green.

Example Cluster Setup: Using Autoconfiguration 2 CC's

For this example, we will use auto configuration to configure a cluster consisting of 2 CC's. Unlike the previous example, we will use the auto configuration option instead of manually creating the cluster. After installing the rXg software on each machine, open a separate browser tab for each machine in the cluster.

Create a new administrator on the Master Controller , by clicking "create new" on the Administrators scaffold. Each admin account should be unique for every operator.

At a minimum a login and password are required. Click create.

Next, edit the License Keys scaffold.

Paste in the license key and click update , this will restart the webserver. Note: if an asset exists in the licensing portal with the IUI of the node, the node will automatically retrieve its license.

Next the CIN (Cluster Interconnect Network) will be created. Navigate to Network::LAN, and create a new network address.

Name : cc1 CIN Address. Set the interface , and specify the IP address in CIDR notation. Leave both autoincrement and span values at 1. Do not check create DHCP pool. Click create.

Turn the rXg into a Master Controller by navigating to System::Cluster. Create a new cluster node by clicking create new on the Cluster Node scaffold.

Verify that the default information is correct. Check the auto registration box, this will allow the automatic registration of cluster nodes. Once that is done, it will open up the permit new nodes option, check this as well. This will allow new nodes to join the cluster so they can auto-register.

Now the auto approve new nodes option will become available. Check this box. By checking this box, the operator of the rXg will not need to approve new nodes that join the cluster. Checking all the boxes makes it so new nodes will not only auto join the cluster but will also be approved without any intervention. If you wish to disallow the auto-approval process, then the opererator will need to approve each node before it will become part of the cluster.

For this example, we are checking all the options so that the process is as automatic as possible. Click create.

Now go to the tab that was opened with the secondary CC's admin GUI. Do not create an admin or apply a license at this time. Scroll down to the bottom of the page and edit the cluster node bootstrap record.

Under the Auto Registration section check the auto registration box, which will enable the node automatically register to the Master Controller. This will unlock the create CIN option and the join as new option. Create CIN will create the cluster interconnect network on the node using the data provided on the form. Check the create CIN box.

The join as new box should be checked if this node has never been a member of this cluster before (such as having a node fail and re-adding it to the cluster after repair - it would not be a new node in this case), check this box. This will allow the operator to select the join role for this node. In this case, it should be set to*standby controller (HA)*.

Enter the controller's IP address in the controller IP field. Set the interface that will be used to connect to the CIN network in the interface field. Set the CIN IP of this node in the local IP address field. The gateway field does not need to be set because the node belongs to the same network as the Master Controller. Click update.

The cluster node bootstrap record will now show that it is awaiting auto-registration.

On the Master Controller navigate to System::Cluster. Both nodes should not be listed in the Cluster Nodes scaffold.

Note that their status may be unlicensed; the licenses can be added via the License Key scaffold below. Edit the record for CC2 and paste in the license. In this case, the nodes have pulled their licenses automatically.

Now that the licenses have been added, it is a fully functional cluster that created itself without the operator needing to copy and paste information between the Master Controller and nodes.

How to change which Cluster Controller is the Master Controller

Turn off network HA on the nodes, leave the Master Controller for last.
Make sure the priority of the standby you want to become the new master is higher than all other standby controllers. Typically, the standby controllers will be a priority of 7 by default. Set the standby that you want to be master to 9.

SSH into the current master. Stop rxgd and kill postgres (you will need to become root for this). Running ' kr' will stop rxgd and then running ' killall postgres' will stop postgres. Once this is done, the highest priority standby will take over as master. You can reduce the HA timeout to make this faster (default is 5 minutes).
Open GUI on the new master. Edit the cluster node record for the current master node and set to standby.
SSH into the node that will be the new master. Run ' console' to access the rails console. Find the BootstrapOption record for the NEW master and set the host , username , and password fields to nil. In this case, the record that will be edited is the last record, since there is only CC1 and CC 2. The record can be found by running ' BootstrapOption.last'.

Edit cluster node record in GUI for new master and set to master.
Edit the bootstrap option record in GUI for old master and set it as if it is a new node.
SSH to OLD master and edit the bootstrap.yml located at /space/rxg/bootstrap.yml. Change the order under _controllers so that the NEW master is on top of the list followed by any other standbys. Repeat for bootstrap_live.yml. After editing the 2 files on the OLD master run ' rr' to restart rxgd. If you changed the control plane HA timeout , be sure to set it back. Finally, edit the cluster node records and re-enable network HA starting , doing the master CC last.

Note: Doing this will not copy over graphing information so it will be lost.

Node Integration After Failure

With HA 3.0 , the process to get a failed node back into the cluster is straight forward. For example, if a node loses a power supply, once it's replaced and the node is turned back on, the node will automatically join the cluster and take over networks configured on it (if another node took over for it).

If the node is replaced with new hardware, meaning the IUI has changed, the cluster node record for the downed node can be edited. Once the IUI is replaced with the new node's IUI , the username and password for the new node will be generated. These can then be entered into the bootstrap and the node will integrate into the cluster and replace the failed node.

Fleet

The Fleet view allows the operator to configure the rXg to be used as a fleet manager or to join a node to an existing fleet manager.

The Fleet Nodes scaffold allows the operator to turn the rXg into a fleet manager and to add nodes to be managed.

The this checkbox indicates that this fleet node record refers to this system.

The manager field, if checked, indicates that this node is the fleet manager.

The host field is used to enter the FQDN or IP address of the Node.

The key will contain the key to be used to authenticate with the fleet manager , or if on a fleet node, it will be a record of the key generated for the node by the fleet manager.

The ignore SSL cert errors field, if checked, will allow the fleet manager to ignore any certificate errors when communicating with the nodes. Note: this is not recommended.

The stat reporting interval field is the interval in seconds that the node will report its stats. When set on the fleet manager node, this value will set the default value, unless overridden on a node record. Default value is 10 seconds.

The fleet groups field allows the operator to set which fleet groups the node will belong to. It is possible for a node to belong to multiple groups.

The PMS properties field allows the operator to set which PMS properties the node belongs to (if configured).

The config templates field allows the operator to select which, if any, templates should be pushed to the node.

The software package field allows the operator to select an upgrade software package to push to the node.

The proxy hostname field is the hostname to use for proxying web and/or SSH traffic. When set on a fleet manager record, it enables cookie-based proxying via the operator portal. When set on a Fleet Node record, enables persistant anonymous Virtual Host behavior.

The certificate field sets the certificate to present for traffic destined to the proxy hostname.

The operator can use the Fleet Groups scaffold to create groups, which can then be used to control who can access those groups by specific admin or administrative roles.

The fleet nodes field allows the operator to specify which nodes belong to the fleet group.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The admins field allows the operator to specify which admins will have explicit access to the nodes in this group, in addition to the admin roles.

The admin roles field allows the operator to select the admin roles that have access to the nodes in this group.

The config templates field allows the operator to push selected config templates to the nodes that are members of this group.

The Software Packages scaffold allows the operator to upload software packages that can then be pushed to fleet nodes for upgrades.

The file field allows the operator to upload an upgrade package to the fleet manager.

The remote URL field allows the operator to specify a URL to retrieve the package from (if not uploading via the file field).

The username field is used for HTTP authentication if required.

The password field is used for HTTP authentication if required.

The fleet nodes field allows the operator to specify which nodes the upgrade package should be pushed to. This is optional; the operator can use the Scheduled Upgrade scaffold to specify which nodes and when the upgrade should take place.

The Scheduled Upgrades scaffold allows the operator to schedule upgrades. Upgrades can be pushed out immediately or can be rolled out over several days, starting at a specific time of day.

The software package field allows the operator to specify which upgrade package is scheduled for install. By default, it will be set to use latest available for OS version. The operator can also specify any software package that has been uploaded using the Software Packages scaffold.

The start at field allows the operator to specify on what day and at what time the upgrade will begin.

The fleet node field is used to specify which node the upgrade will be pushed from.

The this system field specifies that the upgrade will also be pushed to the fleet manager.

The fleet nodes field allows the operator to select specific nodes that will be upgraded regardless of fleet group membership.

The fleet groups field allows the operator to select which fleet groups will be included in the upgrade. If a fleet group is selected, it will push the upgrade to all nodes that belong to that group.

The node CSV field allows the operator to upload a CSV file containing a single column with the names or host values of the fleet nodes to include in this job. This will overwrite any existing nodes that have been selected.

The minimum version field designates that the node must be running at least the specified version in order to upgrade.

If the no alpha builds box is checked, then nodes that are running an alpha build will not be upgraded.

The schedule mode field is by default set to immediate; if set to staggered , it allows the operator to set the number of days the upgrade will take place over and how many nodes should be upgraded per day. The number of days can be changed by deleting or adding a day.

The max concurrent upgrades field sets the maximum number of nodes that can be updated at a time.

The max failures field will pause the job when the specified number of nodes have failed.

The max failure % field will pause the job when the specified percentage of nodes have failed.

Example Fleet Manager Setup

For initial fleet setup, navigate to https://FQDN/admin/menu/fleet.

Create a new fleet node. Name is arbitrary.

This box should be checked if the record being created is for the node being created.

Manager should be checked if the node being created will be the fleet manager node.

Host is the FQDN or IP address of the node.

Fleet groups should be selected to allow the node to be seen by specific groups.

Proxy host can be set if required for proxying web and/or SSH traffic. Select certificate to present for traffic destined to the proxy hostname. Click create.

Fleet groups can be used to group nodes together. For example, nodes can be grouped by property owner. Name is arbitrary.

Fleet nodes is used to select the nodes that will belong to the group.

The admin field sets admins with explicit access to the nodes in this group. The admin roles field sets the admin roles that have access to the nodes in this group.

To add a node to the fleet manager navigate to System::Fleet on the fleet manager node.

Create a new fleet node record by clicking create new.

The name field is arbitrary. Leave both the this and manager boxes unchecked.

Enter the FQDN of the node in the HOST field. Select a group this node will belong to, if applicable. Copy the key in the key field. Click create.

Navigate to https://FQDN/admin/menu/fleet on the node being added to the fleet manager. Enter the FQDN of the fleet manager into the fleet manager host field, and copy the key into this node's key field and click join.

Example Fleet Templates

The operator can use the fleet manager to push config templates to the nodes connected to the fleet manager. This can be done on a per-node basis or to specific groups as defined by the fleet groups.

To push a config template to a node navigate to System::Backup on the fleet manager , and create a new config template.

In this example, a new usage plan will be pushed to nodes in the Lab02 group. The config template must be given a name.

The config to be pushed goes in the config field, or a .yml file containing the config can be added.

Lastly, we select Lab02 Group via the fleet group field. Optionally, the apply template box can be checked which will run the template after creation.

Below is an example showing that the config template was successfully applied to both fleet nodes in the group.

Below are two screenshots. The first is from Billing::Plans before the config template is applied, and the second shows the same scaffold after applying the config template.

Example Fleet Templates #2 - Speedtests

In this example, a template will be used to push speedtest config to all the nodes that the fleet manager controls. Navigate to System::Backup on the fleet manager , and create a new config template.

A speedtest will be configured on all fleet nodes which will then run a speedtest every 8 hours.

The config template must be given a name.

The config to be pushed goes in the config field, or a .yml file containing the config can be added.

Lastly, we want to select all nodes. Optionally, the apply template checkbox can be checked, which will run the template after creation. Click create.

Below is an example showing that the config template was successfully applied to all fleet nodes controlled by the fleet manager.

Below is a screenshot of the configuration of the speedtest pushed to all nodes.

Example Fleet Proxy Setup

Fleet proxy allows the operator to access nodes behind the fleet manager that may not be otherwise accessible due to ACL's in place. To setup the proxy feature we first need to create a certificate.

Navigate to System::Certificates and create a new certificate. Note: the domain name you are using for the certificate should resolve to the primary IP address of the fleet manager node.

Give the certificate a name , then scroll down to the certificate signing request section. Give that a name as well, leave usage set to server, and set the sign mode to generate CSR. Obtain certificate from Let's Encrypt.

Fill out the common name , country code , state , locality , and email address fields with the appropriate information (the other fields are optional). Click create. After a minute or so the new certificate will be retrieved.

Now that the certificate is created, navigate to System::Fleet and edit the fleet node record for the fleet manager.

In the proxy behavior section, set the proxy hostname field to match the FQDN of the certificate created earlier. Select the certificate that matches the FQDN. Click update.

Navigate to the fleet operator portal and there will now be the option to proxy to each node, even nodes that would not be accessible, like the nodes in this example with private IP addresses on the WAN (which is not an officially supported deployment).

Now the fleet manager can be used as a proxy to either access the Admin UI or SSH. To access a node, click on the proxy drop-down for that node and select either admin UI or SSH.

Once the proxy is established the operator will have access to the admin UI of the fleet node , the proxy connection can be ended by clicking end proxy at the top of the admin UI.

Example Fleet Upgrade Setup

To setup a fleet upgrade the operator must first upload the software package that will be used for the upgrade. To upload the software package , navigate to System::Fleet and create a new software package.

Give the software package a name and choose the file, or enter the remote URL and username and password. For this example, the package will be uploaded directly. Once the file is chosen, click create.

Next, create a new scheduled upgrade.

Give the schedule a name. Select the software package uploaded in the previous step. Select a start at date/time.

Next, select the fleet node or fleet groups that should be included in the upgrade. For this example, the scheduling rate will be left at immediate since we are only pushing the upgrade to single node. Click create.

The operator can use the Scheduled Upgrades scaffold to view the status of the upgrade.

Licenses

The Licenses view presents all information and controls necessary to review, obtain, and install a license key for the current rXg.

Detailed View

The licensing summary dialog displays the permitted values of all aspects of the installed license key alongside current utilization.

The accounts field describes the number of end-user accounts in the local database. This represents the total number of end-user accounts that are present in the persistent storage mechanism. The activity of the end-user accounts (or lack thereof) does not have any effect on this parameter.

The login session field describes the number of simultaneous end-users logged in via the captive portal. This includes end-users who have logged in via RADIUS , LDAP , tokens (including free access) as well as locally stored accounts.

The IP sessions field describes the number of simultaneous IP addresses that have traffic transiting the rXg. This parameter is fully inclusive of all sessions regardless of whether they originate from end-users who have logged into the portal or are authorized for access by other means (e.g., MAC groups that have portal disabled).

The MAC entries field describes the number of devices that are L2 connected to the rXg. This parameter is fully inclusive of all L2 devices regardless of whether they are generating traffic that transits the rXg.

The connection states field describes the total number of simultaneous TCP and UDP connections transiting the rXg. A state is a connection between an end-user on the LAN and a server on the WAN. For example, opening Microsoft Outlook to read email from a single email account will typically result in 2 states: one for downloading new emails and a second one to transmit unsent emails. Typical web surfing results in approximately 5 simultaneous states, most of which are TCP HTTP connections downloading web page assets such as images. Some programs such as peer-to-peer file sharing programs may create upwards of 50 or even 100 states. Malicious software such as worms attempting to spread through the Internet will often generate thousands of states.

The VLANs field describes the number of logical interfaces configured on the rXg. Each physical interface of the rXg can have many logical VLAN interfaces. This parameter represents the sum total of all logical VLAN interfaces on all physical interfaces present on this rXg.

The uplinks field describes the number of logical WAN uplinks configured on the rXg. This parameter enables rXg link control features. The rXg can aggregate, fail-over, diversify, and affine traffic among multiple uplinks when configured and licensed to do so.

The RADIUS realms field describes the number of RADIUS realms that are configured on the rXg. In a typical configuration, each realm represents a roaming partner or entity with whom the operator has an agreement to authenticate the partner's database of end-user accounts.

The RADIUS groups field describes the number of RADIUS groups that are configured on the rXg. Each RADIUS group is a pool of end-users who have been authorized by a server specified by one or more RADIUS realms.

The LDAP domains field describes the number of LDAP domains that are configured on the rXg. Each LDAP domain represents a separate administrative group of end-users that can be authenticated via the rXg captive portal via LDAP.

The LDAP groups field describes the number of LDAP groups that are configured on the rXg. Each LDAP group is a pool of end-users who have been authorized by a server specified by one or more LDAP domains.

The account groups field describes the number of account groups that are configured on the rXg. Account groups affect end-users who have logged in via the captive portal using credentials matching a locally stored account. Account groups are often employed to logically group end-users who have purchased different levels of service (e.g., standard versus premium). The rXg integrated billing system employs account groups as destinations for end-users when a purchase of a usage plan is made.

The IP groups field describes the number of IP groups that are configured on the rXg. IP groups are used to logically group operator specified CIDR blocks that should experience similar policy. In a typical deployment, IP groups are used to define the IP addresses that will experience forced browser redirect. Members of IP groups can be as small as a single IP address (/32) or as large as a class A (/8).

The MAC groups field describes the number of MAC groups that are configured on the rXg. MAC groups are used to logically group one or more MAC addresses for policy enforcement purposes. In a typical scenario, MAC groups are used for exceptions to policies enforced globally via IP groups or specifically via account groups. For example, a MAC group may contain the MAC addresses of the operator laptops to enable unfettered and priority access to network administrators.

Installation Unique Identifier

The installation unique identifier (IUI) is a string of characters that uniquely identifies a particular piece of rXg hardware.

The IUI must be supplied with all license requests. License keys are generated for a particular IUI and will not install nor work with an rXg that does not present a matching IUI. The IUI is hardware dependent and cannot be changed by the administrator of the system.

License Keys Scaffold

The License Key scaffold interprets and presents the several dates present in the license key as well as the lifetime of the currently installed license.

In addition, the License scaffold enables the operator to view the current key as well as install a new license key.

To install a new license key , click on the edit link and copy and paste the new key string into the text box provided. Be very careful and precise when copying and pasting. Leaving out a line or even a single character will result in the rXg rejecting the key.

Confirm that the rXg is connected to the WAN before installing a license for the first time. This is needed for time synchronization, which is a prerequisite to installing a license with temporal restrictions. Also, be sure to install the right license key as the keys are generated to match the IUI that is also presented on this view.

Options

The Options view enables the operator to configure global configuration options for the rXg.

The Options scaffolds are designed to easily store and swap between profiles. For example, one set of device options can be stored for each node in an rXg cluster using the Device Options scaffold. This allows a single configuration database to be shared across a cluster. To give the rXg the identity of a particular node, simply mark the appropriate profile as being active. The Network Options scaffold comes pre-populated with a series of packet option profiles for different kinds of networks. If the complexion of the network changes, simply mark the appropriate profile active and the rXg will be reconfigured.

Device Options

The Device Options scaffold enables configuration of global settings governing various core services of the rXg.

The active field enables an option set. Exactly one option set may be active at any time. Enabling a particular option set will automatically disable another existing active option set.

The FQDN setting is the fully qualified domain name that is used to identify this rXg. This will be the domain name that users will be redirected to if using a local splash portal. Your upstream DNS servers and DNS glue records must be configured to resolve the specified DNS name into an IP address configured on the rXg.

The time zone setting configures the GMT offset for the rXg. It is critically important to make sure that this is set correctly to ensure proper billing functionality.

The NTP server field specifies the network time synchronization server. Change this to your internal network time servers for increased time synchronization reliability. If you do not have an internal network time server, choose from one of manypublic NTP servers or use the publicNTP pool.

The SMTP section is used to configure the outbound SMTP server. These settings are used for the email notification and mass email campaign subsystems.

The server address and server port settings enable configuration of an upstream proxy email server. By default, emails are queued to an email MTA locally on the rXg which then delivers directly to the recipients. Setting an SMTP server causes the rXg, to deliver all emails through the specified host.

The username and password fields are the credentials used for the email relay server specified by the server address and server password settings. Leave these fields blank if the email relay server does not require authentication credentials.

The log rotate hour field configures the hour during which the rXg rotates its system log files, restarts critical services, and performs nightly database maintenance. This should be set to the time of least end-user activity, likely in the middle of the night. A time of 4AM is not supported because it conflicts with the Daylight Savings Time (DST) shift.

The start limiting at field is the minimum amount of unauthenticated ssh connections necessary to begin dropping new connections at the percentage defined in the drop rate (%) field. Must be set if drop rate (%) is set. The drop rate (%) field is the rate which new unauthenticated ssh connections will be dropped once the start limiting at number of unauthenticated connections is reached. This will scale linearly up to 100% once the block all at number of connections is reached. Must be set if start limiting at is set. The block all at field is the maximum number of unauthenticated ssh sessions that will be allowed.

DKIM Domains

An entry in the DKIM Domains scaffold enables DKIM message signing of outbound email for the domain specified in the record. DKIM message signing is a technique that allows a sending mail server to prove that it is authorized to send email for that domain.

When enabling DKIM signing, a cryptographic keypair is generated, which will be used to sign the outgoing email. A DNS record must be defined in the public DNS records of the desired domain, which specifies the public key of the generated keypair.

The domain field specifies the domain for which DKIM signing should be enabled. By default, the rXg will use the FQDN of the system to send outbound emails, unless a different "from" address is specified in the Custom Message being sent. If a different domain is used in the Custom Message, then a DKIM Domain should be created for that domain in order to sign outbound email.

The selector field specifies the unique selector that identifies _this_system's public key, since there could potentially be many servers sending email for the same domain. The selector must be the same across all domains that are enabled for a single system. In a cluster, each node could use its own selector, although it is not a requirement. A different DNS TXT record will need to be created for each domain/selector combination.

After creating a DKIM Domain, refreshing the scaffold should show the DNS record name that must be created in the public DNS records, and a button allows the operator to copy the contents that should go into the data field of the DNS record. If the DNS record is not created, servers that receive email that has been signed by this server will not be able to validate the DKIM signature, and may reject the email.

Network Options

The Network Options scaffold enables configuration of global settings that govern the rXg packet manipulation engine.

The active field enables an option set. Exactly one option set may be active at any time. Enabling a particular option set will automatically disable another existing active option set.

The state timeout field governs the expiration of UDP / TCP connection states. The normal setting is the default recommended selection for most applications. The high-latency setting increases the time before expiration occurs and is recommended for satellite uplinks. The aggressive setting reduces expiration timeouts and should be used for highly reliable uplinks, such as a leased-line (e.g., T-1) and situations where a large number of connections are constantly being created and destroyed. The conservative setting changes the expiration policy so that the system goes to great lengths to preserve states even when they are idle despite a much higher memory utilization.

The MAC <=> IP setting affects how the rXg translates a MAC address into an IP address , and vice versa. A value of dhcp,arp configures the rXg to utilize the DHCP leases table and ARP table cooperatively, where the MAC sent by an IP's DHCP client is favored over the MAC determined by the ARP protocol for a given IP address. The arp,dhcp value means the ARP table takes precedence over active DHCP leases. The dhcp and arp values configure the rXg to use only the DHCP leases table or ARP table. Appropriate configuration of this setting is critical for correct operation of numerous rXg features including automatic login.

Using the ARP table is the preferred method of determining the MAC to IP mapping on L2 connected networks. This is because the ARP table is most likely to have up to-the-second information and will also be able to map MAC addresses to statically assigned and misconfigured IP addresses. However, the ARP table will be unreliable in L2 connected networks that have intermediate devices that engage in ARP spoofing. Some wireless radios perform MAC spoofing when used in bridged, mesh or WDS mode. When working with such equipment, the DHCP leases table must be used to determine the MAC to IP mapping.

Using the DHCP lease table to discover MAC to IP mapping is required in L3 routed networks. This is because the rXg will see the MAC address of the next hop router rather than the MAC address of the end-user device for all IPs that are not L2 bridged. Furthermore, intermediate routers must be configured for DHCP relay and use the rXg as the DHCP server. The rXg is unable to use the DHCP leases table to create a MAC to IP mapping for devices that do not use the rXg as the DHCP server , for statically assigned addresses and for otherwise misconfigured IP addresses. The DHCP leases table is also most likely to contain out-of-date information compared to the near real-time ARP table. Thus, it is recommended that the DHCP lease table be used only when the ARP table cannot be used to acquire the correct IP to MAC mapping.

Using either the dhcp,arp and arp,dhcp settings is only recommended when deploying an rXg in a mixed L2 and L3 connected LAN environment. If a rXg deployed to manage a L3 routed fixed wireless broadband network and then is also used to manage a local hotzone that is L2 bridged, then it is necessary to use both the DHCP leases table and the ARP table in order to determine the MAC to IP address mapping. In most cases, it is best to prefer the ARP table over the DHCP lease table because the ARP table is most likely to have the most recent and hence the most correct mapping.

The dhcp,arp and arp,dhcp settings should only be used when absolutely necessary. Conflicts and/or confusion may occur when both the DHCP leases table and ARP table are both used to map MACs to IPs. For example: if the DHCP issues a lease to client A, then client A leaves the network, then at a later time, client B joins the network and acquires a lease for the same IP address, then client A returns to the network, there will be a conflict. The DHCP leases table will report the IP MAC mapping as client B whereas the ARP table may report the IP MAC mapping as client A. This issue is exasperated in situations where long DHCP leases are issued.

Correct IP to MAC mapping is prerequisite for proper operation of several critical rXg features including automatic login. Careful consideration of all available options as well as thorough examination of all available ARP and DHCP instrumentation is strongly advised when configuring this option.

The ARP timeout field dictates how long an ARP entry is held in the cache, in minutes, until it needs to be refreshed.

The maximum MSS setting enforces amaximum segment size on all packets transiting the rXg to be less than or equal to the specified number of bytes. Make sure that the MSS is set less than the MTU of any transit network, otherwise fragmentation will occur again. Typical values of MSS and MTU for Ethernet are 1460 and 1500 respectively. Reductions in MSS are necessary to support certain forms of IP-IP tunneling (e.g., IPsec VPN).

The minimum TTL setting modifies the minimum time-to-live on all packets transiting the rXg. The TTL is a value from 1 to 255 that is decremented each time a packet crosses a router. When the TTL reaches zero, the packet can no longer cross any routers (unless the router is capable of and has been specifically configured to ignore and rewrite the TTL). This modifier is useful for fine tuning performance of very large networks. Boosting the TTL helps in situations where packets are not reaching their targets. Reducing the TTL helps reduce looping of stray traffic. A minimum TTL set to zero disables the TTL normalization. Note that setting a minimum TTL prevents traceroute utilities from operating correctly.

The prioritize ACK setting will prioritize packets with a TOS of low delay and for TCP ACKs with no data payload.

The clear DF bit setting enables or disables the removal of the don't fragment (DF) bit in the IP flags field of packets transiting the rXg. IP fragmentation is a mechanism that enables packets to be broken into smaller pieces to pass through links with a smaller MTU than the original size. In particular, packets with DF unset can be fragmented along their way to their destination by other routers. Enable this option if the packets transiting the rXg (upstream or downstream) are too large for one of the transit routers to handle. The two most common uses of this option are to enable NFS traffic to pass over the WAN and to permit fragmenting of inbound WAN traffic to support IP-IP tunneling (e.g., IPsec VPN) between the end-user client and the rXg.

The randomize ID setting enables or disables the randomization of the data inside IP identification fields. Enabling this prevents fingerprinting of a network from the outside world. Outsiders on the WAN can use the sequential nature of the IP packet ID field to discover the topology of a network protected by NAT. It is recommended that this option be enabled whenever clear DF bit is enabled.

The block policy field defines the response to devices when packets are blocked. The drop setting will silently drop all blocked packets, whereas the return setting will send an ICMP unreachable packet for UDP requests, a TCP Reset for TCP requests, and will silently drop all others.

The Queueing Mode option affects the traffic shaping mechanism and the queues that are built for client devices. When queueing is disabled, no queues are built and ALTQ is disabled. When set to normal mode, a single queue tree is built and packet scheduling and throughput is limited to a single CPU core. When set to parallel mode, packet processing is parallelized across multiple queue trees allowing multiple CPU cores to increase throughput. The number of parallel trees is set by the Tx/Rx Queues option, which requires a reboot if changed. NOTE: use of parallel queueing can result in inaccurate throttling if traffic for a single client traverses more than one tree, since the queue discipline is distinct for each queue tree.

In order to reduce the frequency of firewall queue and ruleset reloads, a set of semi-static queues pools is created, and queues are assigned to clients as needed. The Default Leaf Queue Count field specifies how many queues should be generated for a given pool when there is no prior knowledge of the number of queues required by that pool. When the number of clients nears the size of the pool, the pool is expanded. When a client disappears from the network, its queue assignment can be reclaimed so the queue can be reused by another client without growing the queue pool, since system performance is impacted when there are many queues. The Queue Assignment Timeout option controls how long (in minutes) a queue assignment will be retained before being reclaimed for another client. A shorter timeout will keep queue pools smaller. Setting a value of 0 will disable queue assignment reclamation.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Database Purgers

Entries in the Database Purgers scaffold define rules by which database records are automatically deleted.

The tables field specifies which tables of the database will be affected by this record. Multiple database tables may be selected so that a single purging policy may be applied across several facets of the rXg configuration database.

The timestamp column field determines the database timestamp that will be used in the calculations to determine if a database record is to be purged.

created_at and updated_at Any table may be purged of records using the created_at and updated_at timestamp columns. expires_at Only useful when used in conjunction with coupons. usage_expiration Only useful when used in conjunction with tokens. logged_in_at Only useful when used in conjunction with accounts.

The age field specifies the length of time that must elapse between the current time and the stored value in the timestamp column in order for a record to be chosen for deletion.

The retain records with usage remaining checkbox prevents the deletion of account records that have a non-zero value in their usage (time) field. This checkbox has no effect when the selected table is anything other than account.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

CALEA Options

The Communications Assistance for Law Enforcement Act (CALEA) is the cornerstone of lawful interception in the United States. It is a federal law specifically designed to ensure that, despite rapid advancements in telecommunications technology, law enforcement agencies can still conduct court-ordered electronic surveillance.

Requirements on Carriers and Manufacturers: CALEA places a legal obligation on:
- Telecommunications Carriers: This broadly includes traditional phone companies, mobile carriers, broadband internet access providers, and interconnected VoIP (Voice over IP) providers. They must ensure their networks have the technical capacity to perform lawful intercepts.
- Manufacturers of Telecommunications Equipment: Equipment used by these carriers must be designed with built-in lawful intercept capabilities.
Built-in Capabilities: The core of CALEA is that these capabilities must be designed into the network and equipment, rather than being added on an ad-hoc basis when a warrant is issued. This ensures that intercepts can be executed efficiently and without "undue burden" on the carrier.

Lawful intercept (LI) refers to the process by which a law enforcement agency (LEA), with appropriate legal authorization (typically a court order or warrant), obtains communications network data from a service provider. Under CALEA, this generally covers two main types of information:

Call-Identifying Information (CII) / Metadata (Trap and Trace / Pen Register):
- This is non-content information about a communication.
- Examples: Source and destination numbers (for calls), email addresses (for email, though CALEA's application to information services like webmail is debated), timestamps, duration of calls/sessions, IP addresses, and for mobile phones, cell tower location data.
- This is akin to what a "pen register" (for outgoing calls) or "trap and trace" (for incoming calls) device traditionally captured.
Content of Communications (Full Content / Wiretap / Title III):
- This includes the actual substance of the communication.
- Examples: Voice conversations, the body of text messages, email content, data from internet sessions (e.g., web Browse, chat messages, file transfers).
- This requires a higher legal standard (e.g., a Title III warrant in the U.S.), demonstrating probable cause that a crime is being committed.

The rXg supports LI via the System::Options::CALEA Options scaffold, providing the ability to define the traffic of interest (using the target client MAC address(es) as the trigger) and destination where the captured traffic is to be delivered.

CALEA scaffold

The configuration process involves the following steps: * Name: the name assigned to the CALEA rule being created. This field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold. * Active: this box is checked by default, indicating that the given CALEA rule will be activated once saved. It is possible to create rules and activate them afterwards as well, in which case this box should be unchecked. * Mirror mode: indicates the mirror mode the traffic of interest is subject to. Today, only one mirror mode is supported, in which all traffic of interest is replicated (not sampled) and transmitted to the destination IP address * Destination IP: the destination IP (IPv4 or IPv6) address of the CALEA collector * MACs: in this section, at least one MAC address is configured, describing the traffic of interest to be mirrored and delivered to the target CALEA collector. Enter MAC address of interest in the MAC field, along with an optional note. If more entries are needed, use the Create Another MAC button or the dropdown next to the Add Existing button which allows to select one of the previously defined MAC addresses.

CALEA create

Once created, an example of a CALEA rule is as shown below, where traffic from two separate hosts is collected and transmitted to the CALEA collector at 192.168.150.4.

CALEA example

When and if the same traffic set needs to be delivered to multiple CALEA collectors, multiple CALEA rules with the same set of MAC addresses but different Destination IP addresses need to be created.

The given CALEA rule is active as long as the Active box remains checked. Note that at this time only one CALEA associated mirror rule can be active at a time.

NOTE: The IP address(es) associated with the monitored MAC address(es) must be in a non-Default policy. The association with the Default policy prevents the mirror traffic from being properly tagged for remote forwarding towards the configured collector.

Portals

The Portals view configures the rXg captive portal web application framework enabling self-provisioning and advertising communication for the end-users population.

The primary purpose of the captive portal is to provide a destination for end-users after a forced browser redirect. The end-user population that experiences a forced browser redirect is controlled through the policies subsystem.

The rXg is prepackaged with a default captive portal containing several revenue-generating web applications. Prepackaged end-user self-provisioning modules include sign-up via account creation, payment via real-time credit card processing, usage plan selection, coupon code redemption, viewing and editing of current profile , and more. In addition, the default captive portal includes several modules that assist with the delivery of pre authentication , post authentication , HTML injected , and web session interstitial advertising.

The captive portal infrastructure includes small format device detection and automatic routing of requests made by such devices to alternative layouts and stylesheets. This enables the portal to have unique and independent views for smart phones, PDAs, gaming devices, and other handheld devices.

While the default captive portal is fully functional, it is designed to be a basis for operators to create their own customized portal with operator specific art, identity, and even functionality. The process of customizing the captive portal begins with the creation of a new record in the Custom Portals scaffold on this view.

The rXg employs a caching mechanism to maximize performance of the captive portal web application server infrastructure. Use the restart web server dialog to bring the web application infrastructure into development mode in order to disable caching so that changes made to the custom portal files are immediately reflected in the pages being served. If pages are being loaded onto the rXg via SFTP, click the development button when the pages are finished being uploaded to dump the cache by restarting the web server. Restart the web server back into production mode when done making changes.

In order to customize a portal, the administrator must be enabled with SSH access via the Admins view. In addition, a working knowledge of how to use SSH, SFTP and Ruby on Railsare required. Some excellent books that cover these subjects are SSH, The Secure Shell: The Definitive Guide (ISBN 0596008953), Agile Web Development with Rails (ISBN 0977616630) and The Rails Way (ISBN 0321445619).

Custom Portals

An rXg can have multiple custom captive portals residing on it simultaneously. Each captive portal must have a record in the Custom Portals scaffold. Each captive portal may be assigned to serve a different subset of the end-user population. The mapping between portals and end-users is defined by the policies subsystem.

The name field is an arbitrary string used to identify the portal. This string is used for identification purposes only.

The controller name field is the string used to uniquely identify the portal within the Ruby on Rails web application infrastructure. If the controller name is left blank when a new custom portal is created, the rXg administrative console will automatically generate a reasonable default based on the name field.

The controller name becomes the suffix of the direct access URL. For example, if the controller name is abc the direct access URL is https://rxg.local/portal/abc. The controller name also determines the directory and file name structure that is used to store the custom portal on the filesystem of the rXg. It is very important be precise about the controller name when editing and uploading files to customize the portal.

The Google Analytics web property field stores a Google Analytics web property ID. The format of a Google Analytics web property ID is UA-xxxxxx-xx where the x's are numbers. The web property ID is listed next to the name of a configured profile in a Google Analytics account home page.

When the Google Analytics web property field is populated, the captive portal will automatically include a Google Analytics site tracking code. This allows the operator to easily integrate external, third-party verifiable portal traffic tracking for the purposes of revenue verification and advertising/impression count marketing.

It is the responsibility of the operator to create and maintain a Google Analytics account along with an appropriate profile for the desired web property. For most portals, it is recommended that the operator configure the portal post authentication landing page as a goal so that it is easy to see the ratio of potential end-users to end-users who commit to subscribe.

Operator Portals

The 'Operator Portals' scaffold lists all of the currently configured portals on the given system. Multiple portal types can be instantiated at any time, for example, a fleet manager portal, a front office manager (FOM), and others.

Operator Portals scaffold

When creating a new Operator Portal, several fields needs to be filled in, as follows:

Operator Portal, part 1

The controller name field sets the name of the controller and how you access the operator portal. For example, if the controller name is set to FOM, then the operator portal would be accessed by going to https://FQDN.OF.SYSTEM/FOM.

The default dashboard field allows the operator to specify which dashboard should be displayed when first logging in. By default, this is set to Template Default, but can be changed to any other custom dashboard that exists on the system.

The additional dashboards field allows the operator to select other custom dashboards that are visible in this operator portal, in addition to the default dashboard.

The single sign-on strategies field is used to select which, if any, single sign-on strategies that may be used to log into this operator portal.

The admin ACL field allows the operator to override the active admin controller ACL with the one specified here; the ACL selected here does not need to be marked as active.

The template field lets the operator choose which template this operator portal will be created from. Views and assets that do not exist will be sourced from the selected template. If portal source is set to duplicate, all views and assets will be copied from the selected template when created. Several options are pre-configured, including the Front Office Manager (FOM), Fleet Manager, Conference, IoT, Location Manager (covered in more detail in the following section), and a Precompiled Web App.

The initial contents field sets how the portal will be created. A portal with ' create directory structure only' selected will inherit all views and assets from the FOM portal unless overridden.

If ' duplicate files from template or existing portal' is selected, then a new operator portal will be created and all files will be copied to the directory from the selected source, allowing the operator to edit any of the preexisting views.
If ' Git' is selected then the source portal will be pulled from the Git repository. It is also possible to set a sync frequency when using Git so that any changes made to the repository can automatically be pulled to all systems. Checking ' restart after sync' will restart the webserver if there is change that was pulled and automatically restart the webserver so the changes will take effect.
If ' Archive file via HTTP GET' is selected then the portal can be pulled from a remote site and sync frequency can be configured as well. It is also possible to use ' rsync' which provides the same sync options.

Operator Portal, part 2

The module configuration section allows the operator to specify not only which admin roles have access to the operator portal but can also be used to disable specific modules contained within the operator portals. To select the specific admin roles able to access (interact with) the given Operator Portal, check the box in the 'Allow Access' column next to the selected Admin Role. The example below shows access granted to the in-build Super User accoutn only, effectively disallowing users in any other groups from vewing this portal.

Access control for portal

The visibility of specific modules within the given portal can be further controlled using the 'Disabled Modules' section. The example below is for a Fleet Manager type portal, showing settings disabling all proxy settings in the portal. The level of granularity and list of available control features depends on the portal type.

Feature control for portal

Fleet Manager

The Fleet Manager portal, as the name suggests, is used to manage a fleet of rXg systems deployed in different geographical locations, organized in arbitrary groups depending on the preferred operational scheme. The Fleet Manager portal is used to view status of different fleet groups and nodes, perform group actions on them (including scheduled software updates), generate reports, etc.

Fleet Nodes

The screen below shows a view of a small fleet with two nodes, one of which comprises a cluster of two nodes.

Fleet Manager, main screen

Health metrics for individual nodes can be displayed in a 'Full height', 'Compact', and 'Text' format, by toggling the 'Record Display' option, as shown in the following three screensots.

Full height view of the fleet

Fleet view, full height

Compact view of the fleet

Fleet view, compact

Text view of the fleet

Fleet view, text

There are also sorting and filtering options, selection of the number of elements displayed per page, as well as the refresh frequency. In the large scale deployments of production Fleet Managers, the refresh time may need to be extended to 30 seconds or even longer, depending on the number of nodes reporting to the fleet manager.

The main screen provides an option to add a group using the 'Add a Group' button to create a new logical grouping of several nodes, as well as 'Add a Node' option to add a node to one of the node groups previously created in the system.

To add a new group, fill in the following fields in the respective dialog

The Name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.
The Fleet Nodes allows the operator to assign some of the previously existing nodes to the newly created group. This field can be left empty, if the group does not contain any nodes at the time it is created.
The Note field is an arbitrary string note used to describe the given group. This field may be left empty.
The Admins and Admin Roles fields allow to restrict admin access to the given group to the selected admin accounts (when selected in the Admins field) or admin groups (when selected in the Admin Roles field). At least one of them needs to be populated, and by default, the Admin Roles field is populated with the gropup the accoutn creating the given group belongs to.
The Config Templates field may be optionally used to select which of the configuration templates configured in the system are accessible to the given group. This field may be left empty and individual templates can be added to the given group later on.

Fleet manager, add a group dialog

To add a new node, fill in the following fields in the respectibe dialog

The Name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.
The Host field is filled with the FQDN (must be resolvable via the DNS used by the fleet manager) or the IP address (IPv4 or IPv6) of the fleet node.
The Key field is automatically generated by the dialog itself and will be used to link the new fleet node and connect it to the fleet manager. It may be customized, if needed, but it is recommended to leave it in its default value.
The Fleet Groups field allows to assign the newly created node to one of the existing groups.
The Ignore SSL cert errors field should not be checked in the production conditions to avoid on-boarding potentially insecure fleet nodes.

Fleet managed, add a node dialog

The Fleet Reports screen provides access to a variety of pre-configured reports, providing also an option to create custom ones, as needed. The name of individual report types are pretty self-explanatory and will not be examined in more detail here.

Fleet reports

Config Templates

The Conifg Templates screen provides access to the configuration templates, allowing the operator to create a new configuration template, test it, and apply it to selected node(s) or group(s).

Config templaes, main screen

A config template can be edited using the 'Edit' button, deleted using the 'Delete' button, validated using the 'Test Config' button, and applied using the 'Apply' button to nodes selected under the 'None selected' drop down list.

Additionally, new configuration templates can be created using the 'Add a Config Template' button, with the following fields that need to be populated:

The Name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.
The Note field is an arbitrary string note used to describe the given config template. This field may be left empty.
The File upload allows the operator to upload a YAML-formatted file to overwrite the content of the given config file.
The Remote URL,, Username, Password, and Certificate fields are used for a remote config download process, where the config template is donwloaded from a specific remote location.

Add config template, part 1

The Request properties allows to custom HTTP Header or Query Parameter fields for the given config template. More than one field / entry is possible, by adding new lines using the 'Create Another Request Property' button
The Config field contains the YAML-formatted body of the config template, which may include also embedded Ruby code.

Add config template, part 2

The ERB field should remain checked, which indicates that the given config template is to be processed with the ERB template engine.
The Recurring field allows the operator to set frequency to automatically fetch (if applicable) and apply the config template after first application. Various frequency options are pre-defined, including from hourly to annually, covering the majority of use cases commonly observed in production conditions.
The Fleet Nodes, Fleet Groups, and Excluded Nodes fields provide a flexible way to select which of the node(s) and/or groups to apply the given config template to.
The Retry Every and For fields specify the retry conditions for the given config template, should its application fail. Leave blank to disable retries when a template application fails. The configuration fields allow to specify the retry period in minutes / hours / days / weeks / months and the duration of the retry period (again, in minutes / hours / days / weeks / months).
The Disable Fleet Certificate Verification should not be selected for production conditions and it is only recommended for testing, not production. When checked, the fleet certificates are not being validated, which may lead to a potential of a rouge fleet node have the configuration template applied to.

Add config remplate, paty 3

Automatic Tunnels

The Automatic Tunnels screens allows the operator to use a Tunnel Wizard or Tunnel Visualization for the fleet.

The Tunnel Wizard allows the operator to create instant Wireguard tunnels among the nodes of a fleet group, providing L2 connectivity between the selected nodes.

The wizard includes several steps , including

STEP 1: select the topology (mesh or hub&spoke)
- MESH: Establish a tunnel from every node in the group to every other node in the group.
- HUB & SPOKE: Establish a tunnel from every node in the group to a common hub node.

Wizard, step 1

STEP 2: select the fleet group the connectivity is applicable to

Wizard, step 2

STEP 3: provide the addresses to use for Wireguard interfaces (these caddresses can be private RFC1918 IPv4 address space)

Wizard, step 3

STEP 4: specify a port, keep-alive time, addresses, or IP groups, if needede - this step is optional
- a default Wireguard Port is set to 51820, other port numbers can be used
- a keep alive period can be set to a custom value
- node addresses can be selected - select the addresses for each node that should be accessible via the created tunnels. By default, tunnels will use addresses marked "Wireguard eligible" from the admin UI's addresses scaffold.
- Select the IP Group for each node that should be associated with each of the created tunnels. By default, tunnels will share a new IP group called "WireGuard Default" that will be connected to the default policy.
- there is an option to check to automatically rerun the wizard and apply updates whenever there are changes to fleet nodes within the selected group.

Wizard, step 4

The wizard requires the acknowledgment that running this wizard will make changes to the configuration of all fleet nodes in the selected group, potentially disrupting access to those systems. It is critical that before any Wireguard configuration is committed, backup of all running configurations is taken for all target nodes.

Scheduled Upgrades

The Scheduled Upgrades screen allows to create scheduled upgrades for selected node(s) / group(s).

For starters, go to the Software Packages, and click on the 'Create New' button and fill in the following fields:

The Name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.
The File is where the new firmware file is selected and then uploaded.
The Remote URL,, Username, and Password fields are used for a remote software image download process.

Software Package, create new

Once the software package(s) required for the fleet are created, a scheduled upgrade can be created, using the 'Create Scheduled Upgrade' button. The following fields are available:

The Name field is an arbitrary string descriptor used only for administrative identification. Choose a name that reflects the purpose of the record. This field has no bearing on the configuration or settings determined by this scaffold.
The Software Package is where one of the pre-defined software packages is selected.
The Start at and the Timezone fields are used to select the time when the upgrade process is scheduled to start.
The OS upgrade toggle allows the OS upgrade to take place.
The Minimum version and No alpha builds allow to set the minimum version of the code required (to make sure that the node is running at least the specified version in order to upgrade), and to control whether the node(s) are allowed to run alpha builds or not.

Scheduled Upgrade, page 1

The Schedule mode allows to select when to execute the code upgrade, including the immediate or various types of staggered upgrades. In staggered upgrades, for example upgrades to a specific share of systems per day may be configured, to minimize distuprion to end customers.
The Fleet Nodes, Fleet Groups, and Node csv fields provide a flexible way to select which of the node(s) and/or groups to perform the upgrade on. The CSV file allows also to upload the names or host values for target node(s) to be upgrades.

Scheduled Upgrade, page 1

A Scheduled Reboot schedule can be also created using the 'Create Scheduled Reboot' button, including the following fields:

The Date and Timezone fields are used to select the date/time when the reboot process is scheduled to start.
The Fleet Nodes and Fleet Groups fields provide a flexible way to select which of the node(s) and/or groups to perform the reboot on.

Scheduled Reboot

Once a scheduled reboot even is created, new information fields are displayed on the left side of the screen (specific nodes ot be rebooted and the scheduled time) as well as the calendar view is updated with the scheduled action.

Scheduled Reboot, schedule created

Scheduled events can be deleted / modified by clicking on the target event and changing the desired parameters. For example, to modify a scheduled reboot event, click on the specific calendar entry or select the event on the left, menu option (3 vertical dots), and select Edit. Modify the parameters of the event or delete the action, as needed.

Scheduled Reboot, modify event

The user menu on the right side of the screen permits the operator to change the password, access SSH key options (see the screen below), or log out from the portal.

The SSH key options include:

a line entry for each existing SSH key, containing its name, authorization check box (if checked, the SSH key can be used to log into the shell on ths rXg system), a way to copy of the public key, fingerprint value (hash of the key and its size), an optional private key information, as well as an option to Edit or Delete the given key entry.
there is an option to generate a new key pair (public and private) as well as add an existing SSH keygenerated offline using any of the methods available outside of rXg (Putty, SecurCRT, shell on Linux, Mac, etc.)

SSH key options

Location Manager

The Location Manager is a portal that is aimed at presenting network information in a spatially aware way.

One of its key functionalities is creating and placing POIs (Points of Interest).

POI Edit Menu

Click Here to Create a new POI.

POI Create Button

After you name it, click here to save it

POI Save Button

When you first create it, it will be placed in the center of the floorplan. Make sure dragging is turned on, then simply drag it to where it should be.

POI Dragging Button

Omniauth Strategies

The Social Login Strategies scaffold enables creation, modification, and deletion of login strategies for supported Omniauth providers.

The name field identifies this login strategy in the system.

The provider name field determines which Oauth provider this strategy relates to. Select a supported provider from the list.

The app ID field defines the ID of the application that has been created with the provider chosen in the provider name field. For Facebook, this is the App ID , but for Twitter this is the API Key. This value should be obtained from the developer console of the associated provider.

The app secret field defines the app's secret value which authenticates the app. This value should be obtained from the developer console of the associated provider.

The captive portals selections define for which captive portals this strategy is enabled. This strategy will not be available unless it is associated with at least one captive portal.

The usage plans selections determine which usage plans are available for users who log in using this strategy. The plans selected here must also be associated with the end user's effective portal; however, users who have not logged in via this strategy won't be able to see these plans in the usage plan list. If there are no usage plans associated with this strategy, an account will be created for the user, who will then be redirected to the usage plan list view. If there is only one associated usage plan, and it is free, the plan will automatically be applied to the account.

The SAML section contains configuration options which pertain only to SAML login strategies. When utilizing a SAML strategy, the App ID and App Key are not necessary.

A SAML configuration requires at a minimum, an Identity Provider (IdP) SSO URL, and optionally, a IdP Cert Fingerprint to enable validation of the IdP's certificate. Both the SSO URL and Fingerprint may be determined automatically by providing a IdP metadata URL.

The Service Provider (SP) Entity ID is a unique identifier for the service provider, which will be entered into the IdP when adding the SP.

After creating the login strategy , the webserver will restart. Clicking the show link will provide the metadata URL that can be provided out-of-band to the Identity Provider in order to establish a login trust.

Users who log in with an Omniauth strategy only have access to usage plans that are associated with their strategy AND the current captive portal. Users who log in with a non-social account do not have access to the usage plans associated with the portal's Omniauth strategies.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

A WAN target should be associated with the captive portal where the operator intends to use the strategy which allows the user to access the provider's site for the login process. Twitter, Facebook, and Google WAN targets are created automatically and should be selected when utilizing these providers.

For more information, see the Social Login manual entry.

Remote Access to Local Web Servers

The rXg web multiplexor may be configured to recognize operator specified name-based virtual hosts. This feature enables the operator to configure remote access to web servers that are on the LAN side of the rXg in a reasonable, maintainable and understandable manner. Name-based virtual hosts are most often used for remote access to the web management consoles of privately addressed LAN equipment without VPN. VPNs are the preferred mechanism for enabling remote access to LAN equipment. The next best thing is to use name-based virtual hosts through this feature.

The operator must configure DNS records for each and every name-based virtual host that is desired. The DNS records must resolve to the WAN IP of the rXg. Web requests to the DNS record will contain the HTTP headers that enable the rXg web multiplexor to send the request to the appropriate backend server on the LAN.

The rXg must be configured with either a wildcard SSL certificate or individual certificates per destination host. Each HTTP virtual host entry can be configured to use unique SSL Certificates and should match the configured DNS entry for that host. This is required because HTTP headers are read after the SSL handshake is complete.

The hostname for remote access field specifies the DNS record that has been configured. For example, if the rXg is given the domain name gw.somewhere.net it would be appropriate to use name-based virtual hosts such as wc.gw.somewhere.net, ap003.gw.somewhere.net, sw18.gw.somewhere.net, etc. The chosen domain does not need to be a subdomain of the rXg.

The local server IP field specifies the target IP address(es) of the back-end server(s) for the name-based Virtual Host that is configured by this record. Web traffic sent to the rXg using the hostname configured in this record will be proxied to this IP. Multiple IP addresses can be defined, separated by spaces or newlines. When multiple IPs are defined, requests are load-balanced to the IPs in the list according to the configured Load balancing method.

The available load balanding methods are as follows:

Round-Robin: This is the default behavior. Traffic is distributed in a round robin fashion.
Least Connections: The next request is assigned to the server with the least number of active connections.
Source IP Hash: A hash-function is used to determine what server should be selected for the next request (based on the client's IP address). Subsequent requests from the same client should be send to the same backend server.
Source IP:Port Hash: A hash function based on the client's IP and Port combination
Request URI Hash: A hash function based on the full request URI.
Random: Each request will be passed to a randomly selected server.
Random + Least Connections: Two servers are chosen at random, and the one with the least number of active connections is used.

The WAN Targets association restricts access to this virtual host to only the hosts included in the WAN Target. All other source IPs will receive a 403 Forbidden response when attempting to access using this FQDN.

Custom Data Set

The name field will be used to call the data set in a portal so choose a name that reflects the purpose of the record.

The policies field allows the operator to restrict which policies have access to the custom data set.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The key field specifies which custom data keys belong to the custom data set. When creating a custom data set this field is required; however, a custom data keys does not need to belong to a custom data set to be used.

Custom Data Keys

The dataset field is used to tie a custom data key to custom data set. This is optional when creating a custom data key , but can be used to tie a collection of custom data keys into a single custom data set.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The name field will be used to call the data set in a portal, so choose a name that reflects the purpose of the record.

The value section allows the operator to set what value or values are contained within the custom data key.

The string field is used to store a string value.

The text field is similar to the string field but should be used for large blocks of text.

The Boolean field can be used as a true/false flag. It is false by default.

The decimal field is used to store decimal numbers.

The integer field is used to store whole numbers.

The date field is used to store a specific date.

The time field is used to store the time.

The date-time field is used to store both the date and time.

Attachments

The description field can be used to describe the purpose or a description of the content.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The custom portals field is used to select which customs portals the content will be available for use. Selecting a custom portal here will make the content available to any Captive or Landing portals based off of the Custom Portal selected.

The captive portals field is used to select which specific Splash portals the content will be available on.

The landing portals field is used to select which specific Splash portals the content will be available on.

The file field is used to select the file to upload and make available to the selected portals.

Simple Webpacker Example

Webpacker allows the operator to import pre-compiled JavaScript into a custom portal. In this example, a new custom portal will be created then add the necessary files. Navigate to System::Portals and create a new custom portal. Note: an existing portal if one already exists.

Give the portal a name, and specify the controller name. For this example, just the default portal will be used so no other information needs to be provided. Click create. Note: webserver will restart when a new portal is created.

Once the portal has been created, access the portal files. This can be done via SSH or SMB ; see the Portal Customization section of the help manual for instructions on setting up access. In this example, SSH to the machine and become root.

Now navigate to the portal directory cd /space/portals/demo. Note: portal path may be different if using a different portal or used a different controller name.

Next, create a src directory within the root portal directory. This will be where any desired js files imported using webpacker will be placed. To create directory, use the following command: mkdir src

Navigate to the src directory that was created with the following command: cd src

Next, create a hello.js file. This file will contain the following code:

let hello = "Hello, world!" console.log(hello)

Save the file and go back to the root portal directory cd ..

Edit the pack.js file and add the following line:

import "./src/hello.js"

This will import the JavaScript file created in the previous step. Once the line is added, save the file.

Now the portal JavaScript was added can be hit to and see in the developer tools console as the following:

Update

The Update view presents dialogs enabling the operator to change the version of the rXg software currently running. The operator may choose to automatically update or manually update the rXg.

It is imperative that the operator make a full backup of the rXg (including, but not limited to, the database configuration and the customized captive portals ) before initiating an update. If an update fails for any reason, it may be necessary to restore the rXg from backup.

The rXg automatic update process requires that the operator have a valid support contract with RG Nets. By supplying a valid support credential ( email and password ) assigned to the operator, the rXg will contact RG Nets servers, download the latest rXg software, and automatically perform the update.

The rXg manual update process requires that the operator have a version of the rXg software stored on their local filesystem. The latest versions of the rXg software are available on the rXg servers. Access to the rXg servers requires a valid support contract. The manual update process is useful for operators who have multiple rXgs deployed and wish to minimize the number of times that the rXg software package needs to be downloaded over the Internet.

The Update rXg from a mounted USB or local ISO Disk Image checkbox in this section allows you to use a bootable USB that is connected to the host as the source, OR an ISO file that is loaded into the disk images scaffold (currently only available when there is a virtualization host record defined or when manually loaded into the /space/disk_images directory). This dialog is intended for performing an rxg upgrade not an OS upgrade. The OS upgrade form becomes visible when the official FreeBSD version has changed.

When the box is unchecked, you can also upload an ISO file there to upgrade the rxg version.

Additional Resources

YouTube Playlist - Upgrading an rXg

Admins

The rXg administrative console implements all five tenets of a trustworthy system. Three of the five tenets (authentication, authorization and non-repudiation) are controlled on this view.

Access

Browser-based Access for Human Consumption

API-based Access for Computer Consumption

curl -O http://rxg.dns.entry/admin/menu/download_backup?api_key=fb9c5e...f6349

Administrators

The Administrators scaffold enables creation, modification, and deletion of accounts for administrators of the rXg.

The service account checkbox, if selected, creates an admin that is used only to generate an API key and does not allow the service account to have access to the admin GUI.

The role field defines an authorization policy for this administrator. The permissions for the roles in the list are defined by the Administrative Roles scaffold.

The first name , last name , and department fields are informational fields. They are only used in the Administrators scaffold to identify the administrator.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

Administrative Roles

The Administrative Roles scaffold enables creation, modification and deletion of authorization policies that govern authenticated administrators within the rXg administrative console.

The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.

The SMB checkbox authorizes Samba access to the rXg. Must be accompanied by an active SMB Server which contains to the policy or WAN targets which will be accessing the SMB Server.

The API checkbox authorizes access to the rXg admin web interface when providing a member Admin's API Key as the api_key_query parameter or the _apikey HTTP header.

The master permission authorizes control over global hardware-specific configuration options. Licensing, SSL, configuration backup, and restore are governed by this permission.

Multi-Factor Authentication

The provider dropdown specifies the third-party MFA mechanism to be used for confirming administrator's identity.

The integration key , secret key , and API hostname fields should be completed using information from an application created within the provider's control panel.

When configured to allow access , errors with the configuration file or connection to the Duo service will allow SSH login without Multi-Factor Authentication.

The admin roles selection determines which roles will trigger Multi-Factor Authentication after completing primary authentication.

Duo Multi-Factor Authentication

In order to set up Duo Multi-Factor Authentication with the rXg, you will need to login to your Duo account, or create a new account at https://duo.com/

To do so, click on the applications link on the Duo Dashboard, and then on "Protect an Application".

Next, search for the term "SDK" and click the protect button for the web SDK Application.

Copy the fields in the application details to the appropriate fields in the rXg

Select the admin roles for which Multi-Factor Authentication should be enforced.

To configure Duo for SSH navigate to System::Admins and edit the administrative role for which you would like to enable MFA for SSH.