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.
Navigation and Organization
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 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 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 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 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 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 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.
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.
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.Usernamebackup
SSH 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.
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.
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 _update
field:
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 _lookup
field. 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
Prerequisites
- USB Drive containing bootable rXg image
- USB Drive containing config template YAML file Procedure
- Insert bootable USB drive into machine and follow normal rXg installation procedure
- After installation has completed and machine is rebooting, remove bootable USB drive.
- Insert USB Drive containing config template YAML file.
- Do not create an admin user
- rXg will automatically scan the USB drive for YAML files, and apply them as a config template.
Use Cases
- Bootstrap an initial installation with license and all Admin Users and Roles already created
---
license_key: "CVBB/4+t7KfT7mwgg+VqhnCusC5SCdF7o+jMeK4U82yV343JSAE0sWnc1F6V\n
/0RrJON/unT2XMvAwZXMKxbpdpYIC3WHcaqw24vaqGl2QNFxrj6KDvo5CJ9P\n
hj8aPuU7zX4nrUjQEEYU25lOa/Y/cVdS+jh+Gd3iopB5+/CEuBfSVcKIRSx1\n
EpDV0l58/0WXkDL1WBgumfviduVzrPyebA26+yjGlRsdlMbuQLWcE0qaiJDJ\n
aJI8cAbz2ehD7bTfVv65Tg4swAEKuENNxO9qIY8v7SALAshAhi6ONZcja32u\n
YjZSWk51GZuUdkbRxPdddebprB1Ab1/d7Ob0utFBhfh+OQVSqr7pVynNaRpv\n
P9YXdq86dflyUQ+dGnKZmtrogMFINj8Rv8k7RD6Slp644tZ9YDaDH4AGCFPs\n
xRzNXfDLhgCMyx7t9VHwCXsTHzsaFxhNFD77qHTyAf4rEkPJQTGuxC2VN46F\n
SmTMLztNJxKz7ud0Y9mQVrVr+24R+bNwT83jlYwx9a/YIgF3+oE1eZpXgK3F\n
z+BP0Ey5R5MClNxE+FEtH7/KYpY0iufb1Y9lUcelw9ppmNJNVcEG/OmJzy40\n
3phGQLMbRw7r2v+VMiBvRJRqsdY0EFoPa2PxWhWQNJeWCCAQODi239PfBcCG\n
JCQMedN0fyi8RtZuibWHZfFOXYJo1mJA202/4W/TPxfL2HoZeZuZ6AjB9iqP\n
ji2DFOLVhfHo4t8L4ZfEtu/TAtxhgUjTQ9St26+SB21P5VSmt7V31IIeBSco\n
+vM61bCObLdlapA9dalqBARDqTmjLAn+jgEh6sQ8oe655tK4M7Dd2RLN0VO+\n
nTxHa5/He2c5ROKG8HWrs4Vj0sZQknfyIkStyYUolI66DSKU2VbUImEJ4Y5v\n
8HlSXZjCQ7SbC+v3VUWI83akAX9hhKpxp2NDWlk77gwRkvmX9fpb/wwBENmH\n
eOIWqYlXYoRYNWTo5x327fzwv6bUv0tYSIk1eQ0xArzF546O1MX0C2T/5ptf\n
zTEmB/IJgQ3NTZRP+yFGOVim3SV05/0hJBsykkUt+Ked3Xpa7RsUQeT8pyMq\n
1ggtm66+M+jTFl7SsHemrc3vzQu/OUrGMEgeNaHO1Dx9KLn1p5CQumhkrSUN\n
Lzd+mSUnxOkD+fOLDduNRX9mSG8zTQz8GYF2+pqx2BAnzUxjrUs+HBpfSvlU\n
4USn6LYVtDyoBPpL"
AdminRole:
- name: RG Nets
system_permission: readwrite
policies_permission: readwrite
identities_permission: readwrite
instruments_permission: readwrite
ssh_enabled: true
master_permission: readwrite
billing_permission: readwrite
archives_permission: readwrite
conference_mode: admin
custom_emails:
- Health Notice Create (notification)
- Health Notice Cured (notification)
- name: WebGUI Only
system_permission: readwrite
policies_permission: readwrite
identities_permission: readwrite
instruments_permission: readwrite
ssh_enabled: false
master_permission: readwrite
billing_permission: readwrite
archives_permission: readwrite
conference_mode: admin
custom_emails:
- Health Notice Create (notification)
- Health Notice Cured (notification)
Admin:
- login: rg
first_name: Romeo
last_name: George
email: [email protected]
crypted_password: "$2a$11$NRMhuaklja/lksdjfglhkUe9Y/GP0jceg6hZRYDrbLufnO0Y2ZN4tO"
admin_role: Super User
company: RG Nets
preferred_contact: email
ssh_keypairs:
name: ndk authorized SSH key
public_key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAgYhNrfb8Kncs1H7fHc1AhEJzgQ......
authorized: true
- login: dgray
first_name: Dorian
last_name: Gray
email: [email protected]
crypted_password: "$2a$11$Dpl1oXpIv9r3yt5mATWujeDQ255NuQ8L0edjAKGuox3ByAO7y2lUK"
admin_role: WebGUI Only
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, andshell
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 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 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 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 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 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 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.
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 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 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 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 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 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 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 controller 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.
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 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 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.
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.
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.
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).
Click Here to Create a new POI.
After you name it, click here to save it
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.
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 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 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.
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 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 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 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 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 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 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.
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.
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.Usernamebackup
SSH 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.
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.
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 _update
field:
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 _lookup
field. 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
Prerequisites
- USB Drive containing bootable rXg image
- USB Drive containing config template YAML file Procedure
- Insert bootable USB drive into machine and follow normal rXg installation procedure
- After installation has completed and machine is rebooting, remove bootable USB drive.
- Insert USB Drive containing config template YAML file.
- Do not create an admin user
- rXg will automatically scan the USB drive for YAML files, and apply them as a config template.
Use Cases
- Bootstrap an initial installation with license and all Admin Users and Roles already created
---
license_key: "CVBB/4+t7KfT7mwgg+VqhnCusC5SCdF7o+jMeK4U82yV343JSAE0sWnc1F6V\n
/0RrJON/unT2XMvAwZXMKxbpdpYIC3WHcaqw24vaqGl2QNFxrj6KDvo5CJ9P\n
hj8aPuU7zX4nrUjQEEYU25lOa/Y/cVdS+jh+Gd3iopB5+/CEuBfSVcKIRSx1\n
EpDV0l58/0WXkDL1WBgumfviduVzrPyebA26+yjGlRsdlMbuQLWcE0qaiJDJ\n
aJI8cAbz2ehD7bTfVv65Tg4swAEKuENNxO9qIY8v7SALAshAhi6ONZcja32u\n
YjZSWk51GZuUdkbRxPdddebprB1Ab1/d7Ob0utFBhfh+OQVSqr7pVynNaRpv\n
P9YXdq86dflyUQ+dGnKZmtrogMFINj8Rv8k7RD6Slp644tZ9YDaDH4AGCFPs\n
xRzNXfDLhgCMyx7t9VHwCXsTHzsaFxhNFD77qHTyAf4rEkPJQTGuxC2VN46F\n
SmTMLztNJxKz7ud0Y9mQVrVr+24R+bNwT83jlYwx9a/YIgF3+oE1eZpXgK3F\n
z+BP0Ey5R5MClNxE+FEtH7/KYpY0iufb1Y9lUcelw9ppmNJNVcEG/OmJzy40\n
3phGQLMbRw7r2v+VMiBvRJRqsdY0EFoPa2PxWhWQNJeWCCAQODi239PfBcCG\n
JCQMedN0fyi8RtZuibWHZfFOXYJo1mJA202/4W/TPxfL2HoZeZuZ6AjB9iqP\n
ji2DFOLVhfHo4t8L4ZfEtu/TAtxhgUjTQ9St26+SB21P5VSmt7V31IIeBSco\n
+vM61bCObLdlapA9dalqBARDqTmjLAn+jgEh6sQ8oe655tK4M7Dd2RLN0VO+\n
nTxHa5/He2c5ROKG8HWrs4Vj0sZQknfyIkStyYUolI66DSKU2VbUImEJ4Y5v\n
8HlSXZjCQ7SbC+v3VUWI83akAX9hhKpxp2NDWlk77gwRkvmX9fpb/wwBENmH\n
eOIWqYlXYoRYNWTo5x327fzwv6bUv0tYSIk1eQ0xArzF546O1MX0C2T/5ptf\n
zTEmB/IJgQ3NTZRP+yFGOVim3SV05/0hJBsykkUt+Ked3Xpa7RsUQeT8pyMq\n
1ggtm66+M+jTFl7SsHemrc3vzQu/OUrGMEgeNaHO1Dx9KLn1p5CQumhkrSUN\n
Lzd+mSUnxOkD+fOLDduNRX9mSG8zTQz8GYF2+pqx2BAnzUxjrUs+HBpfSvlU\n
4USn6LYVtDyoBPpL"
AdminRole:
- name: RG Nets
system_permission: readwrite
policies_permission: readwrite
identities_permission: readwrite
instruments_permission: readwrite
ssh_enabled: true
master_permission: readwrite
billing_permission: readwrite
archives_permission: readwrite
conference_mode: admin
custom_emails:
- Health Notice Create (notification)
- Health Notice Cured (notification)
- name: WebGUI Only
system_permission: readwrite
policies_permission: readwrite
identities_permission: readwrite
instruments_permission: readwrite
ssh_enabled: false
master_permission: readwrite
billing_permission: readwrite
archives_permission: readwrite
conference_mode: admin
custom_emails:
- Health Notice Create (notification)
- Health Notice Cured (notification)
Admin:
- login: rg
first_name: Romeo
last_name: George
email: [email protected]
crypted_password: "$2a$11$NRMhuaklja/lksdjfglhkUe9Y/GP0jceg6hZRYDrbLufnO0Y2ZN4tO"
admin_role: Super User
company: RG Nets
preferred_contact: email
ssh_keypairs:
name: ndk authorized SSH key
public_key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAgYhNrfb8Kncs1H7fHc1AhEJzgQ......
authorized: true
- login: dgray
first_name: Dorian
last_name: Gray
email: [email protected]
crypted_password: "$2a$11$Dpl1oXpIv9r3yt5mATWujeDQ255NuQ8L0edjAKGuox3ByAO7y2lUK"
admin_role: WebGUI Only
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, andshell
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 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 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 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 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 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 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.
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 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 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 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 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 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 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 controller 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.
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 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 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.
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.
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.
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).
Click Here to Create a new POI.
After you name it, click here to save it
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.
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 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 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
Network
The rXg operates on the principle that it is the router between a distribution network which is connected to the end-user population and one or more uplinks where resources reside. Physical, data-link and network connectivity must be established in order for an rXg to deliver control, communication and cognizance over the end-user population. The network menu enables the operator to access the views of the administrative console to create and edit the IP addresses, routing tables, address translation configuration needed to establish L3 connectivity.
End-users must each be assigned an individual IP address so that the rXg can deliver the full spectrum enforcement and instrumentation capabilities. End-users may be assigned public or private IP addresses depending on the desired network topology. The operator may choose to utilize both both private and public addresses at the same time. The rXg may be configured to perform or network address translation on any private (or public for that matter) addresses on the LAN block.
The rXg supports nearly any IP topology imaginable. End-users may be either L2 or L3 connected to the rXg. All capabilities, including the forced browser redirection to a captive portal, are fully supported regardless of whether end-users are L2 connected or L3 connected. L2 connected end-users may be connected natively or via VLANs. L3 connected end-users transit routers that forward blocks configured statically or via dynamic routing protocols.
In the simplest case, the rXg is deployed as the router for a natively addressed LAN that is L2 bridged into the rXg such as the example shown above. The rXg may be configured to natively route public or private blocks and NAT may be enabled or disabled on each block.
In larger RGNs, the rXg is often configured to be the termination point of several VLANs that connect to end-users. In the example above, VLANs are used to segregate traffic between end-users who are originating traffic from two geospatially distinct properties on the same resort. The use of VLANs helps to maximize the performance of the network through traffic segregation.
Traffic segregation is a critical aspect of designing large scale RGNs. VLANs are the most common mechanism to accomplish this, but an alternative network topology is to use L3 segregation as depicted in the example shown above. To accomplish this, routers must be deployed on the LAN side of the rXg. End-users are then connected to blocks that are behind the routers. The rXg must be configured with static or dynamic routing so that the end-user traffic will pass appropriately.
Network Dashboard
The network dashboard presents an overview of the current status and configured settings for the WAN, LAN and routing subsystems of the rXg.
The left column presents a dialog containing the configuration and status information for each of the uplinks configured on the rXg.
Numerous details about the uplink are displayed in the dialog. The colored icon at the upper left of the dialog informs the administrator about the status of the uplink. A green light indicates that the uplink is online while a red one indicates that the uplink is offline. Real-time configuration information is presented in the dialog. For example, if the uplink is set to request network configuration via DHCP, the IP, subnet mask and gateway obtained from the DHCP server is presented.
The top of the middle column presents information about the physical and logical interfaces connected to the rXg.
Each interface that is physically connected and has a link is reported along with the MAC address and media type. The media type is read from the interface when the view is loaded making this an ideal place to determine the speed and duplex of an auto-negotiated link. Clicking on the dialog brings up a view with more detailed information.
The bottom of the middle column presents a snapshot of the routing table of the rXg.
The most utilized routes are presented here. Clicking on the scaffold brings up a view with more detailed information.
The right column presents a set of dialogs describing the LAN IP addresses configured on the rXg.
Use these dialogs to quickly review what IP addresses are configured into which interfaces.
WAN
The WAN view presents the scaffolds associated with configuring the wide area network interfaces.
An rXg requires at least one properly configured entry in the uplinks scaffold in order to function. If more than one uplink is configured, the rXg can aggregate and failover WAN uplinks. In addition, the rXg can affine and diversity LAN traffic over the WAN uplinks.
An uplink must be configured with a valid IP address and gateway to function. To use DHCP to obtain an IP address and gateway dynamically, simply check the DHCP checkbox in the uplink record. As an alternative, a static IP address may be manually specified by creating a record in the addresses scaffold and associating the record with an uplink. The gateway for a statically assigned IP block must be manually configured in the uplink record. If the upstream ISP requires PPPoE authentication, configure the ISP supplied credentials into a record of the PPPoE scaffold and associate the record with the uplink.
Ethernet Interfaces
An entry in the ethernet interfaces activates and configures a physical port on the rXg to take part in in networking connectivity.
In most cases, at least two ethernet interfaces must be configured (one for the WAN, one for the LAN). In multiple uplink scenarios, it is common to have one ethernet interface configured for each WAN uplink. It is also possible to use VLANs on a single ethernet interface to configure unlimited WAN and LAN interfaces.
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 port field determines the physical ethernet port that this record will activate and configure.
The media field configures the speed and duplex of the Ethernet port. In most cases, the autoselect setting will automatically negotiate the fastest possible link. Autoselect should also be used if automatic crossover detection is required as most Ethernet hardware will disable automatic crossover if anything other than autoselect is specified as the media type.
If physical link cannot be established, first check the physical cable using an isolation test. If the cable is determined to not be the issue, try setting the ethernet interfaces on both sides of the cable to the same speed and duplex. Note that if a straight cable is connected between two nodes, that cable will need to be replaced with a crossover because automatic crossover detection will be disabled when a media type other than autoselect is specified. In addition, using a lower speed setting and avoiding full-duplex communication may be necessary when the cable is long or does not meet the standards needed for higher speed communication.
The MTU setting configures the maximum transmission unit (frame size) for this interface. By default, most ethernet interfaces support 1500 bytes. Large MTUs may be used in gigabit networks that support jumbo frames to obtain better throughput when transferring large files. Support for jumbo frames must be present throughout the infrastructure in order for larger MTUs to work properly.
The addresses , uplink , VLANs and PPPoE fields link an Ethernet interface to a configuration defined by the specified scaffold. These fields shown here are mainly presented for informational purposes. In most scenarios, an administrator will link the address, uplink, VLAN or PPPoE configuration to the Ethernet interface using the other scaffold.
The backup port field specifies an alternative ethernet interface to assign the addresses , uplink , VLANs and PPPoE configuration settings when this ethernet interface goes down. An ethernet interface is marked as down if it loses link or if all of the ping targets associated with it go offline. The VLANs and Network Addresses associated with an ethernet interface are moved to the backup port when the ethernet interface is marked as down. The backup port mechanism is designed to be used with generic L2 switching. Backup ports should not be used with any LAG/MLT/SMLT/LACP configuration on the connected switch.
The checksum offload , TCP segmentation offload and large receieve offload settings offload the specified processing to the NIC hardware when possible. In some cases this may cause instability and in other cases there are performance benefits.
Uplinks
An entry in the uplinks scaffold declares a specified logical interface as a WAN uplink. At least one uplink must be configured for proper rXg operation. More than one uplink may be configured in link control scenarios when the operator has obtained multiple WAN drains. When multiple uplinks are configured, the rXg can aggregate and failover between uplinks as well as diversify and affine LAN traffic amongst them.
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 priority field determines the order of precedence during failover in a link control scenario. When only one uplink is configured, this field has no effect as there is no uplink to failover to. When multiple uplinks are configured and connection aggregation is enabled, a failure of a link will cause another member of the pool to forward all traffic. If aggregation is not enabled, or all uplinks within a pool have failed, then the uplink with the highest priority amongst all of the remaining uplinks will be used to forward the traffic.
The interface , PPPoE and VLAN drop downs specifies the mechanism by which this uplink will forward traffic upstream. Only one option may be selected for each uplink.
The DHCP checkbox enables the DHCP client for this uplink. The network address, subnet mask and default gateway of this uplink are requested from the DHCP server. If a statically configured IP address is desired, leave this checkbox cleared, create a record in the addresses scaffold and associate it with this uplink.
The gateway IP specifies a statically assigned default gateway for this uplink. The default gateway must be within the IP block defined by the network address associated with this uplink. This field should remain blank if the DHCP checkbox is set.
The upload speed and download speed fields describe the throughput of the uplink.
Network Addresses
An entry in the network addresses scaffold defines an IP block that will be associated with an interface, uplink or VLAN.
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 IP field specifies the IP address using CIDR notation that will be configured on the interface specified. If the address record will be used for configuring multiple addresses on the interface via the span field, the IP field configures the first (lowest) IP address of the range.
The span field specifies the range of IP addresses configured by this address record. The default value of 1 is assumed if this field is omitted. For LAN links, a span of 1 is typical. For WAN links, a span of greater than 1 automatically enables translation pooling in NAT scenarios. In addition, bidirectional network address translation (BiNAT) requires the WAN link to span one additional address for each BiNAT.
PPPoE Tunnels
An entry in the PPPoE tunnels scaffold enables the point-to-point protocol over Ethernetclient to connect with the specified credentials through an Ethernet interface for the purpose of configuring a valid uplink.
The username and password fields specify the credentials for the PPPoE client. The credentials are assigned by the upstream ISP.
The service name is an optional service selector. If the upstream ISP did not provide a specific value, leave this field blank.
The interface field associates this PPPoE tunnel with an Ethernet interface. It is highly recommended that an Ethernet interface associated with a PPPoE tunnel be used exclusively for this purpose. Avoid associating addresses, VLANs, and other entities with an Ethernet interface that is designated for a PPPoE tunnel.
The uplink field associates this PPPoE tunnel with an uplink. To use PPPoE, an uplink must be associated with a record in the PPPoE tunnels scaffold, which in turn, is associated with a Ethernet interface. Do not associate an uplink that has a PPPoE tunnel enabled with the Ethernet interface directly.
DNS Servers
An entry in the DNS servers scaffold specifies an upstream DNS server to use for DNS resolution.
It is highly recommended that at least one upstream DNS servers be configured for network resilience, else the built-in DNS server is used for resolution. Without DNS resolution, no networking services will operate.
Many ISPs will provide DNS server entries. These DNS servers should be configured into this scaffold. In a link control scenario where multiple uplinks from a diverse set of ISPs are configured in parallel, the DNS servers for all of the upstream ISPs should be configured with the appropriate uplink setting selected. In this case, theGoogle Public DNS or OpenDNS servers may be used as backup DNS servers for all uplinks.
The IP field specifies the IP address of the DNS server that is to be used for DNS queries. In most cases, the upstream ISP will provide the IP addresses for the public DNS servers for a specific uplink. If no servers are provided, using the Google Public DNS orOpenDNS is a good alternative.
The uplinks field associates uplinks with the DNS server specified in this record. In many cases, the upstream ISP will have DNS servers that are restricted to their customers so it is important to make sure that the right IP is associated with the proper uplink.
Configure IPV6 to IPV4 Tunnel
In this example we will configure the rXg with an IP tunnel that will allow us to access IPv6 addresses over an existing IPv4 connection. The IPv6 tunnel end point is provided by https://ipv6.he.net after passing a basic certification process. We will need to create an IP Tunnel, an Uplink, a Network Address, and lastly a DHCP pool. To begin navigate to Network::WAN.
First we will create an IP Tunnel.
Give the IP Tunnel a name. The Type field should be set to GIF. Set the Local Interface field to the WAN interface. The Remote IP field is the Server IPv4 Address obtained from he.net. The Tunnel Local CIDR field is the Client IPv6 Address obtained from he.net. The Tunnel Remote IP is the Server IPv6 Address obtained from he.net. Click Create.
Next create a new Uplink, give the uplink a name, priority should be lower than your primary uplinks. Change the IP Tunnel field to the IP Tunnel created in the previous step. Click Create.
Next create a new Network address to create the LAN DHCP addresses that the system will hand out to IPv6 enabled clients. Give the Network addresses a name, select the ethernet interface the addresses will be configured on, and fill out the IP field with the information obtained from HE, in the Routed IPv6 Prefixes section. Note that the address given ends with :: which is invalid so append the IP you want to assign to the system usually 1. Checking the Create DHCP Pool box is optional, for this example setup it will not be checked and we will create the DHCP pool. Click Create.
Next navigate to Services::DHCP and create a new DHCP pool. As long as the last address created was the address from the previous step it will auto fill the fields. It may be a good idea to reduce the scope of the pool by changing the end IP from 2001:470:1f07:210:ffff:ffff:ffff:ffff to 2001:470:1f07:210::ff. Click Create
Now if we SSH into the machine and run ifconfig gif0 we should see our intferface configured with the IPv4 Tunnel addresses as well as the IPv6 Address, and we should be able to ping an IPv6 addressing using ping6 like ping6 google.com.
NAT
The NAT view presents the scaffolds that configure settings to modify the network address translation mechanisms of the rXg.
NAT
Entries in the NAT scaffold configure network address translation between LAN subnets and WAN addresses.
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 addresses and static routes field specify the source LAN subnets for which network address translation will be enabled by this record.
The uplinks field specifies the destination WAN address(es) to which the selected LAN will be network address translated.
The Reverse NAT field specifies that traffic sent via selected Uplink is to be NATd to the first IP of the selected Addresses. This option is primarily used when the upstream ISP routes a block of public IPs to the rXg's primary uplink IP (often assigned via DHCP), and those IPs are assigned to a LAN interface for distribution to clients, but there is a need for outbound traffic from the rXg to always be sourced from the routed block of IPs rather than the DHCP uplink IP.
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.
If no records are present in the NAT scaffold, the rXg will automatically enable NAT from subnets that are configured with RFC 1918 specified private addresses.
Static IPs
An entry in the Static IPs scaffold creates a one-to-one mapping between an IP address within a span associated with an uplink and a private IP address on the LAN . This feature is typically used to give public access to a resource that is configured on a private IP address such as a web server.
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 Source IP field determines the destination of the translation of traffic originating from the Public IP.
The Public IP field specifies the IP address within a span of addresses associated with an uplink that will be translated to the Source IP.
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.
Dynamic BiNAT Pools
An entry in the Dynamic BiNAT Pools scaffold specifies a range of IP addresses that may be dynamically assigned to devices whose account has a Max BiNATs value of 1 or greater, and whose policy is enabled for this Dynamic BiNAT Pool. This feature is typically used to give public access to a resource that is configured on a private IP address such as a web server or a gaming device which requires open incoming firewall ports for proper operation.
The end-user may subscribe to a usage plan which allows Dynamic BiNAT, and may enable BiNAT functionality for specific device(s) by accessing the manage devices page of the portal. The operator may also change the active BiNAT device(s) by editing the account's device list. Care must be given to ensure that the range of addresses configured here is large enough to accomodate the number of devices that are configured for Dynamic BiNAT.
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 Start IP field determines the first IP address of the range of uplink addresses that will be used as the Dynamic BiNAT IP for eligible devices. The IP should fall within a span of addresses associated with an uplink that is associated with the device's link control.
The End IP field specifies the last IP address in the range of uplink addresses that will be used as the Dynamic BiNAT IP for eligible devices. The IP should fall within a span of addresses associated with an uplink that is associated with the device's link control.
The Policies field specifies policies that may utilize this BiNAT Pool. When an associated Policy contains Accounts, a number of IP's specified in the Max BiNATs field of the Account will be assigned to that Account. The end user will be able to configure up to that many DMZ devices through the manage devices page in the captive portal. When an associated Policy contains devices that do not belong to an account, such as from an IP group or MAC group, a BiNAT will be assigned to each device currently connected that belongs to the associated Policy. If no policies are associated with this BiNAT pool, the pool is effectively disabled, and the addresses will be available for regular NAT.
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.
Example BiNAT Deployments
Below are 3 BiNAT deployment examples.
Example 1: Dynamic BiNATs
In this example the operator has configured the rXg to have a block of public IP address that are used for CGNAT and another pool that users can dynamically be assigned a public IP address from that can used as NAT for the account. This IP can be assigned to a specific device (DMZ), and can also be used for UPNP.
First a block of public IP address must be assigned to an interface.
Next we need to configure a BiNAT pool by going to Network::NAT , in this case half the public IP addresses will be used for BiNAT's. The Operator can control which accounts/clients can be assigned a BiNAT by selecting the Policies that can use the pool. In this case only users in the Residents-Premium policy will be able to draw from the pool.
Being in the Residents-Premium policy is not all that is required the account must also be set to allow the use of BiNAT IP address. This is controlled by the Usage Plan the user has purchased. This can be set by going to Billing::Plans. Edit the appropriate Usage Plan and look at the Sessions section of the account. Here the Operator can set the number of Max dedicated IPs , in this example it is set to 1. UPnP has also been selected in this case.
Now users who purchase the Residents-Premium plan will have a BiNAT assigned to their account that all the traffic from their devices will NAT through and their devices can create UPnP port forwads automatically.
Example 2: Static Dedicated BiNATs
In this example the rXg has been configured so that each account gets assigned a BiNAT that is static. First a block of public IP addresses must be configured.
Next the BiNAT pool must be configured to consume the entire block of public IP address, and the appropriate policies must be allowed access to the BiNAT pool. Network::NAT.
The account must also be set to allow the use of BiNAT IP address. This is controlled by the Usage Plan the user has purchased. This can be set by going to Billing::Plans. Edit the appropriate Usage Plan and look at the Sessions section of the account. Here the Operator can set the number of Max dedicated IPs , in this example it is set to 1. By checking the Static dedicated IPs box the NAT IP or IPs are reserved and remain staic for the lifetime of the account. UPnP has also been selected in this case.
In this example each account is assigned a BiNAT address when created, and the IP assigned will remain for the lifetime of the account. This is the equivalent of having a static public IP address.
Example 3: BroadBand On Demand
In this example the rXg has been configured so that each account selects the number of Dedicated IP's (BiNAT addresses) that will be assigned to the account at time of purchase. A block of Public IP address must be configured via Network::WAN.
Next the BiNAT pool must be configured to determine which IP address can be used for dedicated IPs, and the appropriate policies must be allowed access to the BiNAT pool. Network::NAT.
The Usage Plans for this example must be configured to allow the user to pick the number of Dedicated IPs by using the Plan Addons scaffold via Billing::Plans. Here two Plan Addons have been created allowing the user to purchase additional Dedicated Ips and allows them to make them static by purchasing the static IP option.
The above configuration allows the user when purchasing a plan to select how many dedicated IP's they want and can purchase the ability to make them static as well.
NAT Reversal example
Video Configuration Guide and Demonstration
In this example a NAT rule will be created for NAT Reversal, it will be assumed here that the ISP is handing out a private IP address and routing a static block of public IP addresses to the private IP address. Traffic that originates from the WAN IP address of the rXg will be NAT'ted to the first IP address of the public static block on the LAN. What this means is that if a client device were to go to whatismyipaddress it would report the first IP address of the static block on the LAN and not the WAN IP address. Inbound traffic from the Internet destined to the first IP address of the public static block on the LAN is now redirected to the WAN IP address of the rXg. This means that if the operator were to put in their browser the first Public IP address from the static LAN block, they would be getting to the WAN of the system.
To configure this there needs to be a WAN uplink that would usually be a static IP address however it could be DHCP that assigns a static IP, and there needs to be a block of static Public IP addresses routed to the uplink IP. Below is an example Uplink configuration that receives a WAN IP via DHCP.
To configure this with an assigned static WAN IP address, create a new Uplink or edit an existing one. Select the interface. Make sure the DHCP box is unchecked, and enter the gateway IP address. Create or update the uplink.
Next create a new Network Address and assign the IP address to the uplink. Give the Network Address a name, and select the interface, the interface should match the interface of the Uplink. Enter the address to be assigned to the uplink and click create.
Next the Static Block of Public IP address will be created. Create a new Network Address. Give the record a name, select the interface that matches the uplink in this case it is vmx1. Enter the IP address in cidr notation. Only a single IP address is needed here however we can assign more to the system by adjusting the span if needed. Setting the span to 2 in this example would assign the .2 and .3 address to the system. Click Create.
Next navigate to Network::NAT and create a new NATs rule.
Give the record a name, select the Uplink and check the Reverse NAT box. Next select the Network Address created in the previous step and click Create.
With this configuration in place, a device on the LAN that goes to whatismyipaddress.com would report that it's IP address was 192.170.0.1. A device going to https://192.170.0.1/admin would get the Admin GUI of the system, even though the uplinks IP is a private address.
LAN
The LAN view presents the scaffolds associated with configuring the local area network interfaces.
An rXg requires at least one properly configured LAN address in order to function. To configure an IP address on an interface, create a record in the addresses scaffold and associate it with an Ethernet interface record. If the LAN distribution network is connected via an 802.1Q VLAN trunk, create VLAN interfaces using the VLANs scaffold and then associate address records with the VLAN interfaces.
Ethernet Interfaces
An entry in the ethernet interfaces activates and configures a physical port on the rXg to take part in in networking connectivity.
In most cases, at least two ethernet interfaces must be configured (one for the WAN, one for the LAN). In multiple uplink scenarios, it is common to have one ethernet interface configured for each WAN uplink. It is also possible to use VLANs on a single ethernet interface to configure unlimited WAN and LAN interfaces.
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 port field determines the physical ethernet port that this record will activate and configure.
The media field configures the speed and duplex of the Ethernet port. In most cases, the autoselect setting will automatically negotiate the fastest possible link. Autoselect should also be used if automatic crossover detection is required as most Ethernet hardware will disable automatic crossover if anything other than autoselect is specified as the media type.
If physical link cannot be established, first check the physical cable using an isolation test. If the cable is determined to not be the issue, try setting the ethernet interfaces on both sides of the cable to the same speed and duplex. Note that if a straight cable is connected between two nodes, that cable will need to be replaced with a crossover because automatic crossover detection will be disabled when a media type other than autoselect is specified. In addition, using a lower speed setting and avoiding full-duplex communication may be necessary when the cable is long or does not meet the standards needed for higher speed communication.
The MTU setting configures the maximum transmission unit (frame size) for this interface. By default, most ethernet interfaces support 1500 bytes. Large MTUs may be used in gigabit networks that support jumbo frames to obtain better throughput when transferring large files. Support for jumbo frames must be present throughout the infrastructure in order for larger MTUs to work properly.
The addresses , uplink , VLANs and PPPoE fields link an Ethernet interface to a configuration defined by the specified scaffold. These fields shown here are mainly presented for informational purposes. In most scenarios, an administrator will link the address, uplink, VLAN or PPPoE configuration to the Ethernet interface using the other scaffold.
The backup port field specifies an alternative ethernet interface to assign the addresses , uplink , VLANs and PPPoE configuration settings when this ethernet interface goes down. An ethernet interface is marked as down if it loses link or if all of the ping targets associated with it go offline. The VLANs and Network Addresses associated with an ethernet interface are moved to the backup port when the ethernet interface is marked as down. The backup port mechanism is designed to be used with generic L2 switching. Backup ports should not be used with any LAG/MLT/SMLT/LACP configuration on the connected switch.
The checksum offload , TCP segmentation offload and large receieve offload settings offload the specified processing to the NIC hardware when possible. In some cases this may cause instability and in other cases there are performance benefits.
In this example, there is no redundancy as there is only one path between the rxg and all network switches. If the rxg loses connectivity with Switch A, Switch B, C, and D will also lose access.
A slightly better version of the above configuration would be to add a Backup Port so that if the primary link to switch A becomes unusable, a secondary link can be utilized.
Edit the primary interface, select several Ping Targets , then select a Backup Port.
In this example, when Igb3 loses link or all Ping Targets fail to respond, the VLANs and Network Addresses associated with Igb3 are moved to the Backup Port Igb2. Igb3 is marked as down.
However, this still leaves Switch A as a single point of failure. Consider the below topology for a higher level of redundancy.
This feature is not dependent on proprietary protocols and as such will work with most any available switch.
Sample Topology: Redundant Core Switches
Sample Topology: Redundant Gateways and Core Switches
Pseudo Interfaces
VXLAN
VXLAN, or Virtual Extensible LAN, is a network virtualization technology designed to address limitations of traditional VLANs (Virtual Local Area Networks) in large environments. VXLAN tunnels Layer 2 Ethernet traffic over a Layer 3 IP network by wrapping local area network data packets inside IP packets for transport across a larger IP network. VXLAN overcomes the limited number of VLANs supported by traditional methods. It uses a 24-bit identifier, allowing for millions of virtual networks compared to the roughly 4,000 of standard VLANs.
Bridge
The bridge interface allows two or more interfaces to have a connection between them at Layer 2. This essentially combines them into a single logical network segment, allowing devices connected to either interface to communicate directly with each other.
LAGG
LAGG, which can also be referred to as LAG (Link Aggregation Group), stands for Link Aggregation. It's a networking technology that groups multiple physical network interfaces together into a single logical interface. This essentially combines the bandwidth and, in some cases, provides redundancy for network connections.
Multiple Interfaces, One Logical Interface: By aggregating several physical interfaces, LAGG creates a single, high-bandwidth logical interface. This can be beneficial for applications requiring a lot of data transfer, like video streaming or large file transfers.
Increased Bandwidth: The combined bandwidth of all the physical interfaces in the LAGG is available to the logical interface. For instance, if you combine two 1 Gbps interfaces using LAGG, you'd get a logical interface with a potential bandwidth of 2 Gbps.
Redundancy: In addition to increased bandwidth, LAGG can also provide redundancy. If one of the physical interfaces in the LAGG fails, traffic can still be transmitted over the remaining active interfaces. This helps to improve network uptime and fault tolerance.
Protocols: There are different protocols for LAGG interfaces, with the most common one being LACP (Link Aggregation Control Protocol). This protocol negotiates with a compatible switch to automatically bundle the physical interfaces into a LAG. Both the switch and the device using LAGG need to support LACP for this to work.
Other protocols included Failover, Load Balance, Round Robin, and Broadcast.
WireGuard
WireGuard is a streamlined approach to virtual private network (VPN) protocols. It emphasizes three key aspects:
Ease of use: WireGuard is designed to be simpler to set up and use compared to other VPN protocols like OpenVPN. This is achieved by having a lean codebase and focusing on essential functionalities.
High performance: WireGuard prioritizes speed. It uses modern cryptographic techniques and a streamlined approach to achieve faster connection speeds and lower latency compared to traditional VPN protocols.
Security: Despite its simplicity, WireGuard offers robust security. It utilizes state-of-the-art cryptography and keeps the attack surface minimal by design.
SoftGRE
A SoftGRE tunnel is a type of tunneling protocol that uses Generic Routing Encapsulation (GRE) to transport Layer 2 Ethernet traffic over an IP network. In simpler terms, it encapsulates Ethernet data packets within GRE packets, allowing them to be sent across an IP network that wouldn't normally support them.
SoftGRE tunnels are particularly useful for extending WiFi networks. They can be used to connect geographically separated WiFi access points (APs) to a central rXg, creating a seamless network for users.
The following configuration steps provide an example of how to configure the rXg as an endpoint for a SoftGRE tunnel.
- 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.
- Set the Interface type to SoftGRE.
- The Members field indicates where tunneled traffic can egress. In this example, only tagged traffic on VLAN 777 will be accepted. Interfaces can be used for untagged traffic and VLANs will be used for tagged traffic.
- In the SoftGRE Listen Interface you will set where incoming SoftGRE connections will be accepted from. Polices will be used to identify LAN side tunnels and WAN Targets will be used to identify tunnels originating from the WAN.
Vendor Specific Configuration Examples - RUCKUS SoftGRE Tunnel
SoftGRE Tunnel Troubleshooting
Confirm the presence of interface bridges The bridge number will be the same as the VLAN with an extra 1 at the beginning. For example if vlan2000 should be carried over the tunnel, you should also have a bridge12000. In our example, there will also be an additional 0 because the VLAN ID is only 3 digits. VLAN 777 becomes bridge10777.
This can be confirmed via SSH with the following command:
ifconfig | grep bridge10777
Confirm the traffic is flowing over the bridge interface
This can be done by using tcpdump
to confirm that you see unicast traffic over the interface. For example, have a client connect and ping 4.2.2.2.
Continuing the use of bridge10777, I will use the following tcpdump
statement tcpdump -ni bridge10777
and confirm that I can see unicast traffic from my client device.
VLANs
The rXg defines a logical 802.1Q virtual LAN interface for each entry in the VLANs scaffold. A good reference for understanding VLANs and trunk ports is Network Warrior (ISBN 0596101511) by Gary Donahue.
Creating a VLAN implies that the Ethernet interface that is directly associated with it is a VLAN trunk port. The device connected to the Ethernet interface must be similarly configured to accept traffic for the VLAN ID specified in this record.
The Physical Interface drop down associates this VLAN logical interface with an Ethernet interface. A VLAN logical interface presents itself in the same manner as a Ethernet interface for network address configuration and policy management purposes. However, the VLAN must be associated with an Ethernet interface so that it knows what physical port to transmit and receive on.
The Service VLAN drop down associates this VLAN with a Q-in-Q parent VLAN interface. Note: if using Q-in-Q the operator should make sure that VLAN hardware filtering is disabled on the Ethernet Interface by navigating to Network::LAN editing the interface and confirm that the VLAN hardware filtering box is unchecked.
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 VLAN ID is an integer value that is used in the VLAN identifier field of the frames transferred over the physical interface defined by this record. The field is 12-bits in the ethernet frame, making the range of values from 0 to 4096. The 0 value is reserved for native traffic and 1 is used for management by many bridges and switches. In addition, 4095 is reserved by most implementations.
The I-SIDs (Backbone Service Instance Identifier) can be used to identify any virtualized traffic across an 802.1ah encapsulated frame.
The Autoincrement drop down changes how VLANs are configured with regards to the number of subnets. none | single L2 | n tags=1 will result in a single VLAN being associated to a single subnet or subnets. per-subnet | auto-increment L2 w/L3 | n tags = subnets / ratio means the number of VLANs that will be configured is the number of Subnets divided by the ration. With a Ratio of 1 and tied to a Network Address that has 32 subnets, 32 VLANs will be configured. With a Ratio of 2 and a Network Address with 32 subnets, 16 VLANs will be configured (32 / 2 = 16).per-IP | auto-increment L2 over split L3 via BNG | n tags = (usable IPs / ratio)means if we have a Network Address configured with 32 usable IP addresses the number of VLANs that will be configured is the number of IP address divided by the ratio. Given a Network Address with 32 usable IP addresses and a Ratio of 1, 32 VLANs will be configured. If the Ratio is set to 2, 16 VLANs will be configured (32 / 2 = 16).
The Ratio field is the number of autoincrement subnets or usable IPs in each VLAN tag.
The MAC Override allows the operator to adjust the MAC address(es) assigned to each VLAN interface created based on this VLAN configuration. The MAC address assigned to each VLAN will be the MAC Override incremented for each VLAN interface created. The first VLAN interface created will use the value of MAC Override. For each additional VLAN created, the value will be incremented by 1. For example a MAC Override of ff:ff:fe:00:00:1a with a vlan tag of 10 will result in a MAC address of ff:ff:fe:00:00:1a being assigned to the vlan10 interface. When using autoincrement, vlan11 will be assigned ff:ff:fe:00:00:1b , vlan12 will be assigned ff:ff:fe:00:00:1c , etc.
The addresses field associates one or more network addresses with this VLAN logical interface. All interfaces, including logical VLAN interfaces, must have one or more network addresses associated with them in order for them to pass traffic.
The Switch Port Profiles field allows the operator to associate the VLAN(s) to a switch port profile that will automatically configured the VLAN(s) to the switch ports attached to the profile.
The WLANs field allows the operator to associate the VLAN(s) to a WLAN.
The Conference options field allows the operator to associate the VLAN(s) to a conference record so the VLAN(s) can be used when created a conference via the Conference Tool.
Network Addresses
An entry in the network addresses scaffold defines an IP block that will be associated with an interface, uplink or VLAN.
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 IP field specifies the IP address using CIDR notation that will be configured on the interface specified. If the address record will be used for configuring multiple addresses on the interface via the span field, the IP field configures the first (lowest) IP address of the range.
The span field specifies the range of IP addresses configured by this address record. The default value of 1 is assumed if this field is omitted. For LAN links, a span of 1 is typical. For WAN links, a span of greater than 1 automatically enables translation pooling in NAT scenarios. In addition, bidirectional network address translation (BiNAT) requires the WAN link to span one additional address for each BiNAT.
Examples using Autoincrement
1. Autoincrement with 1:1 VLAN per subnet (MDU)
In this example the VLAN is configured per-subnet with a ratio of 1, this means that each subnet will have it's own VLAN tag. The number of VLANs used will be the number of subnets divied by the ratio. For this example there will be 128 /24 subnets tied to the VLAN which will result in 128 VLANs.
Create a new VLAN Interface , give it a name, select the Physical Interface the VLANs will be tied to. Set the VLAN IDs field to first VLAN to be used. Autoincrement is set to per-subnet , and Ratio is set to 1. If the Network Address is created already it can be selected, in this case it does not, click Create.
Next create a new Network Address , give it a name. Under the Interface section set the Ethernet field to select, and the VLAN field to the VLAN created in the previous step. Set the IP field to the desired starting network address using CIDR notation. Next set the Autoincrement field to the desired number of subnets to create, in this case it will be set to 128. Check the Create DHCP Pool box and then click Create.
Now there are 128 /24 subnets that have been created (10.0.0.1/24-10.0.127.1/24), and 128 VLANs have been configured (100-227) tied sequentially to the subnets.
2. Autoincrement with more than 1 subnet per VLAN
In this example the configuration will put more than 1 subnet into each VLAN. The number of VLANs in this case will be the number of subnets divided by the ratio. In this example there are 64 /30 subnets and the ratio will be set to 4. In this configuration there will end up being 16 VLANs configured.
Create a new VLAN Interface , give it a name, select the Physical Interface the VLANs will be tied to. Set the VLAN ID's field to the first VLAN to be used. Autoincrement is set to per-subnet , and Ratio is set to 4. If the Network Address is created already it can be selected, in this case it does not, click Create.
Next create a new Network Address , give it a name. Under the Interface section set the Ethernet field to select, and the VLAN field to the VLAN created in the previous step. Set the IP field to the desired starting network address using CIDR notation. Next set the Autoincrement field to the desired number of subnets to create, in this case it will be set to 64. Check the Create DHCP Pool box and then click Create
With this configuration there are 64 /30 subnets with 4 subnets per VLAN. 64(subnets) / 4(Ratio) gives us a total of 16 VLANs.
3. BNG with many VLANS inside a single subnet.
The autoincrement BNG feature enables a single subnet to be divided amongst a large number of VLANs. Autoincrement BNG maximizes public address space distribution efficiency. A public /24 CIDR block would typically need to be divided into 64 /30 CIDRs for distribution amongst subscribers. Each of the /30 CIDRs would then be assigned to a unique layer 2 microsegment. Thus a /24 CIDR block would typically support 64 subcscribers. This is an inefficient use of public IPv4 address space.
Network | VLAN |
---|---|
76.77.78.0/30 | VLAN 1000 |
76.77.78.4/30 | VLAN 1001 |
76.77.78.8/30 | VLAN 1002 |
â‹® | â‹® |
76.77.78.248/30 | VLAN 1062 |
76.77.78.252/30 | VLAN 1063 |
The autoincrement BNG feature enables efficient distribution of public static IPv4 24 CIDR blocks. For example, a /24 CIDR block can support 253 subscribers where each subscriber is microsegmented onto their own unique layer two on the distribution infrastructure. It may help to think of this as autoincrementing VLAN assignment via /32s instead of /30s. The difference is that all of the /32s share a single gateway that is accessible from all VLANs. In reality the BNG autoincrement mechanism enables distribution of the addresses on a /24 subnet to ensure client compatibility. This enables efficient use of address space while enforcing true segmentation through a universally compatible standards-based approach.
Network | VLAN |
---|---|
76.77.78.2/24 | VLAN 1000 |
76.77.78.3/24 | VLAN 1001 |
76.77.78.4/24 | VLAN 1002 |
â‹® | â‹® |
76.77.78.253/24 | VLAN 1251 |
76.77.78.254/24 | VLAN 1252 |
In the example below, autoincrement BNG microsegments each usable IP address in 76.77.78.0/24 onto a unique VLAN. VLAN 3002 on igb3 is configured with the first address of the CIDR 76.77.78.1/24 as if the entire CIDR were configured onto VLAN 3002. All of the usable IP addresses of CIDR 76.77.78.0/24 (76.77.67.2/24 to 76.77.78.254/24 inclusive) would normally share the same VLAN 3002. However with autoincrement BNG enabled, the usable IPs are spread across VLANs 3002 to 3254 inclusive.
Autoincrement BNG is unique in that it allows all client devices to share the same default gateway despite being microsegmented at layer 2. In this example, all client devices in VLANs 3002 to 3254 inclusive use 76.77.78.1/24 as their the default gateway. Sharing a single layer 3 default gateway IP address amongst a large number of layer 2 microsegmented clients dramatically improves the efficiency of IP address consumption.
It is important to note that only VLANs 3002 to 3254 inclusive are usable on igb3 when autoincrement BNG is enabled on igb3. It is impossible to assign additional VLANs to igb3 that fall outside of the BNG range as this would interfere with the autoincrement BNG functionality in the configuration described above. An operator may use Q-in-Q if they wish to configure both both BNG and non-BNG VLANs on the same physical interface. This is what we will discuss next.
In this example a single service VLAN (SVLAN 100) will be created and used as the parent VLAN that will contain many client VLANs (CVLANs 1000 to 1352 inclusive). Putting VLAN tags inside other VLAN tags is referred to as a Q-in-Q network architecture.
First create a new VLAN Interface that will be the parent VLAN that will contain the many VLANs. Give it a name. Select the Phyiscal Interface the VLAN will be attached to. Set the VLAN IDs that will be the parent VLAN. Set Autoincrement to none. If there are any Switch Port Profiles configured they can be added here to add the VLAN to any necessary ports. Click Create.
Next configure the VLAN pool that will be tied to the parent VLAN created in the previous step, these VLANs will be tied to IP address in that will be created in the next step as needed. Create a new VLAN Interface and give it a name. The Physical Interface should be unselected and the Service VLAN should be set to the Parent VLAN created in the previous step. The VLAN IDs should be set to the first VLAN to be used. Autoincrement should be set to per-ip , Ratio is set to 1. There is no need to select a Switch Port Profile as these VLANs will not be seen by the switch. Click Create.
Next create a new Network Address , give it a name. Under Interface the Ethernet field should be set to -select- , and the VLAN field should be set to the VLAN created in the previous step. Enter the IP address in CIDR notation in the IP field. The Autoincrement and Span field should be set to 1. Checking the Create DHCP Pool box will automatically create a DHCP pool for the addresses. Click Create.
With this configuration we have a VLAN (VLAN 1000), that contains our BNG VLANs (VLANS 100-352) which allows for the BNG VLANs to be assigned individually to a single IP within the BNG Addresses that were configured. Multiple IPs can be assigned the same VLAN within the address pool as needed and each assignment only consumes a single IP instead of a minimum of 4.
The use of the Q-in-Q network architecture allows a single physical interface to be used with multiple autoincrement BNG interfaces as well as static or dynamically configured VLANs. For example:
Here we see multiple BNG interfaces are created to support distinct downstream distribution equipment. We also see that there is an additional SVLAN that is dedicated for management infrastructure. The standards based nature of the autoincrement BNG approach enables unparalleled flexibilty and diversity. Any VLAN-aware distribution equipment, wireline or wireless, may participate in an autoincrement BNG deployment. In fact, it is even possible to have a single distribution infrastructure composed of equipment from multiple vendors and even mixing different forms of technology. A single installation may use BNG to efficiently distribute public IP addresses across DSL, GPON, DOCSIS, fixed wireless and PLTE all within the same deployment.
Routing
The routing view presents the scaffolds that configure settings to that control the static and dynamic entries into the rXg routing table.
The routing table of an rXg governs where packets are forwarded based on their desired destination. In a basic rXg installation where end-users are L2 connected to the LAN side of the rXg which is in turn connected to a single uplink, the routing table that is automatically created by the rXg is sufficient. In this case, no changes should be made to any of the scaffolds on the routing view.
If the rXg is deployed with a L3 routed distribution network for end-user access, then the rXg must be informed of all connected networks in order to properly route traffic and deliver forced browser redirection. This is typically accomplished by creating static routes for the various subnets that are connected behind L3 routers on the LAN side of the rXg.
The rXg supports distribution and integration of routes via RIP primarily for the purposes of simplifying cluster management. When an rXg cluster is deployed and routing between end-users on different nodes is desired, the rXgs must be informed as to all of the subnets that are behind the various cluster nodes. In addition, the rXg may broadcast router discovery responses to LAN nodes so that they may build up the internal routing tables on LAN nodes. This is particularly useful for LAN nodes that are locally and remotely accessible servers as this provides a simple mechanism for dynamic failover between multiple cluster nodes.
Static Routes
An entry in the static routes scaffold creates an entry in the IP routing table of the rXg.
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 destination field configures the CIDR block for which a specific gateway is needed.
The gateway is the IP address of the next hop router for the CIDR block specified in the destination field.
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.
RIP
The RIP scaffold controls the behavior of the rXg with respect to RFC 1058 and RFC 2453 router information protocol messages. The rXg may be configured to broadcast route advertisements as well as accept RIP announcements from other routers.
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 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 transmit RIP checkbox enables the broadcast of route advertisements to locally connected networks. When this box is checked, the rXg will make RIP announcements
The receive RIPv1 and receive RIPv2 checkboxes enable the rXg to receive RIPv1 and RIPv2 route advertisements respectively.
The RIPv2 password field configures the shared security credential that will be used when sending and receiving RIPv2 announcements.
The trusted gateways field is where the operator specifies the routers from which RIP announcements will be accepted. In order to prevent injection of false routers, it is required that one or more trusted gateways be specified in order to receive RIP announcements.
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.
Wired
The Wired view presents the scaffolds associated with configuring the wired distribution layer of your network, and monitoring/configuring the switch ports throughout your infrastructure.
Switches
An entry in the switches scaffold defines a piece of switching equipment with which the rXg will communicate for the purpose of effecting dynamic VLAN changes when necessary due to a policy shift for a device on the network.
When a device's VLAN assignment has changed due to a policy shift, the rXg will connect to the switch associated with the device's RADIUS realm via the protocol specified in the configuration, and force a disconnect/reconnect, which will reinitiate the RADIUS authentication process, thereby resulting in the new VLAN assignment being applied to the client device.
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 device section specifies information of equipment being configured. Fields with bold text are required. Choose the appropriate option from the supported device types drop-down menu.
Enabling the Monitoring checkbox results in the rXg attempting to import and synchronize Switch Ports from the device, as well as perform ping monitoring of the switch itself, and collect CPU and Memory statistics, where possible.
The SNMP community field specifies the SNMP community string that will be used when attempting to gather CPU and/or Memory information, as well as to collect Switch Port utilization/error/discard data for graphing.
The Switch Fabric field assigns a switch fabric profile to this switch. The Loopback IP , System name , and SPB-m nickname fields must be provided when assigning a switch fabric profile. After supplying the necessary information, the Config sync status link becomes available in the scaffold.
For switches that support configuration management, the Config sync status column contains a link that allows the operator to access bootstrap instructions and enable synchronization.
When bootstrapping a new switch, the operator may retrieve bootstrap commands that will bring a factory default switch or wireless controller into the necessary state to participate in the fabric network, which may be copy/pasted into a console session on the device.
After initial bootstrapping and network connectivity is established, the operator may download a running configuration backup or compare the current running configuration to the expected configuration, based on the associated configuration elements. If changes are needed, they may be pushed to the switch. After successfully synchronizing manually the first time, future configuration changes will be pushed to the device whenever relevant configuration changes are made in the database.
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.
Switch Fabric
An entry in the Switch Fabric scaffold defines the fabric area of a 802.1aq Shortest Path Bridging-MAC (SPB-m) deployment. All participating fabric switches share the common configuration found here. In addition, each participating fabric switch should have an Infrastructure Device defined with the necessary SPB-m configuration specific to that device.
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 Management I-SID field specifies the I-SID that will be associated with the Management VLAN for management traffic. The Management VLAN is configured per device, under the Switches scaffold.
The Manual area field specifies the IS-IS area that will be used within this fabric in the format: xx.xxxx (ex: 10.0001)
The Primary B-VLAN and Secondary B-VLAN fields indicate the VLANs which will be used for passing encapsulated traffic between participating fabric switches on switch ports designated as NNI ports. These VLANs should be unused elsewhere in your infrastructure.
Switch Ports
Entries in the Switch Ports scaffold are created automatically by enabling the Monitoring checkbox on a supported switch's Infrastructure Device. Ports are imported and speed, packet, error and discard rates are gathered via SNMP and made graphable for each switch port.
The name field represents the port's identification in the switch, and should not be changed.
The NNI Port designates this port as a Network-to-Network Interface. This option must be enabled for any port where two fabric-enabled switches interconnect.
The speed in bps field represents the port's maximum physical speed in bits per second.
Switch Port Profiles
Entries in the Switch Port Profiles scaffold define the behavior of downstream wired infrastructure device ports. Switch port profiles enable an operator to manage virtually unlimited switch ports, without configuring them individually.
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 Default checkbox, declares the selected switch port profile as the default for any newly imported switches
The Move Ports checkbox, if selected, will move ports associated with a different default profile to a profile upon save. This should be used in conjunction with the Default checkbox.
The Ports field defines individual switch ports to associate with this profile.
The Native VLAN field is used to define the untagged VLAN that ports associated to a profile should use.
The Shutdown checkbox declares ports associated to this profile to be disabled.
The VLANs field defines the VLANs that should be tagged on ports associated with a profile.
The RADIUS drop-down menu can be used to enable 802.1x or MAC Authentication Bypass, on ports associated to a profile.
The native I-SID specifies the network that untagged traffic from this port should be placed into when building a Fabric configuration script.
The NNI Port designates this port as a Network-to-Network Interface. This option must be enabled for any port where two fabric-enabled switches interconnect.
Wireless
The Wireless view presents the scaffolds associated with configuring the wireless distribution layer of your network, and monitoring/configuring the access points throughout your infrastructure.
WLAN Controllers
An entry in the WLAN controllers scaffold defines a piece of wireless equipment with which the rXg will communicate for the purpose of effecting dynamic VLAN changes when necessary due to a policy shift for a device on the network.
When a device's VLAN assignment has changed due to a policy shift, the rXg will connect to the WLAN controller associated with the device's RADIUS realm via the protocol specified in the configuration, and force a disconnect/reconnect, which will reinitiate the RADIUS authentication process, thereby resulting in the new VLAN assignment being applied to the client device.
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 device field specifies the type of equipment being configured. Choose the appropriate option from the supported device types drop-down menu.
The enable telemetry boolean completely controls whether the rXg will attempt to receive and process telemetry data at all.
The Instrument from Telemetry checkbox results in the rXg using telemetry data to instrument the Access Points and Wireless Clients for this controller, instead of the regular API integration. If telemetry is enabled, the rXg will always instrument radio and client data, regardless of whether instrument from telemetry is enabled.
Enabling the Monitoring checkbox results in the rXg attempting to import and synchronize Access Points from the device, as well as perform ping monitoring of the Infrastructure Device itself, and collect CPU and Memory statistics, where possible.
The SNMP community field specifies the SNMP community string that will be used when attempting to gather CPU and/or Memory information, or Access Point data from WLAN controllers where an API is not available.
The NB portal password and NB portal usernames are used when executing API calls against RUCKUS's northbound portal interface. These must correlate with what is configured in the controller.
The Telemetry username and Telemetry password are used when authenticating an MQTT session with this WLAN Controller. These must correlate with what is configured in the controller's northbound data streaming subscriptions.
Vendor Specific Configuration Examples
For Infrastructure Devices which support configuration management, the Config sync status column contains a link that allows the operator to access bootstrap instructions and enable synchronization.
When enabling automatic WLAN controller configuration management, the operator should ensure that the timezone and country code set in the Device Options scaffold are accurate as they will be used when configuring wireless infrastructure.
After initial bootstrapping and network connectivity is established, the operator may download a running configuration backup or compare the current running configuration to the expected configuration, based on the associated configuration elements. If changes are needed, they may be pushed to the controller. After successfully synchronizing manually the first time, future configuration changes will be pushed to the device whenever relevant configuration changes are made in the database.
Vendor Specific Configuration Examples
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.
Piglet Sensor
Piglets are small, low-cost, raspberry pi based, sensors that can be used for a variety of purposes. Adding a WLAN Controller with a device type of "Piglet" and a host address of "127.0.0.1" in this scaffold will allow the piglet sensors to discover the rXg for adoption. Click Here to access the piglet documentation.
WLANs
An entry in the WLANs scaffold defines a wireless network that you wish to deploy on a supported WLAN controller.
The SSID field specifies the WLAN SSID that will be broadcast and visible to users.
The Encryption selection specifies the encryption algorithm which will be used for this WLAN.
The Authentication selection specifies the type of authentication that should take place in order for users to join the network. In order for Dynamic VLANs to be assigned, authentication must utilize MAC Authentication Bypass or one of the 802.1X methods.
The Default VLAN field specifies the VLAN that users should be placed into, assuming it is not overriden by Dynamic VLAN behavior.
The Tunnel checkbox instructs access points to build a tunnel to the controller or some other location, depending on the vendor, instead of locally bridging the client traffic.
Application Examples: - RUCKUS SoftGRE Tunnel
The Enabled checkboxes allow the operator to enable or disable a WLAN for a particular radio across all profiles where it is utilized.
Dynamic VLANs require the association of at least one VLAN record which is tied to a RADIUS Realm.
The RADIUS Accounting checkbox instructs the Access Point to send accounting information to the RADIUS server as users join, use, and leave the network.
The Access Point Profiles selection specifies which Profiles should include this WLAN.
Access Point Profiles
An entry in the Access Point Profiles scaffold defines a set of common configuration parameters to be applied to a set of Access Points.
The Default checkbox indicates that this Profile will be the default Profile for this Infrastructure Device. Any Access Point which has not been explicitly assigned to a Profile will be placed into this Profile.
The WLANs association defines whoch WLANs will be broadcast on Access Points that fall into this Profile.
The Access Points association allows the operator to explicitly assign a profile to one or more Access Points. Selected Access Points which do not belong to the Infrastructure Device that the Profile is assigned to will be automatically deselected upon saving.
The Management VLAN field specifies which VLAN the Access Points in this profile will use to attempt to obtain an IP address via DHCP.
The 2.4GHz Data Rates and 5GHz Data Rates fields allow the operator to restrict the types of devices that may join the network to only those supporting a specific subset of data rates. By default, 802.11b rates are disabled to improve network performance.
The 2.4GHz Antenna Gain and 5GHz Antenna Gain fields allow the operator to specify antenna gain values (in dBi) that will be applied to Access Points which use external antennas.
The Outdoor APs checkbox instructs the system to enable or disable outdoor power and channel tables for the radios in order to be compliant with regulatory rules.
Access Points
Entries in the Access Points scaffold are created automatically by enabling the Monitoring checkbox on a supported wireless controller's Infrastructure Device. Status and statistics are gathered on an ongoing basis via API and/or SNMP.
After creation, the operator may reassign an Access Point's Access Point Profile in order to control the WLAN and radio settings applied to it. Access Point details are updated on a regular basis via background interaction with the Infrastructure Device.
Access Point Radios
Entries in the Access Point Radios scaffold are created automatically by enabling the Monitoring checkbox on a supported wireless controller's Infrastructure Device. Status and statistics are gathered on an ongoing basis via API and/or SNMP.
Access Point Radio Profiles
Entries in the Access Point Radio Profiles scaffold can be assigned to WLANS in the Access Point Profiles scaffold. The HW Mode Preference field ia a comma separated listing of supported radio type, 'A' (5 Ghz, 802.11 A and 802.11 AC), 'B' (2.4 Ghz 802.11 B), or 'G' (2.4 Ghz 802.11 G). The order matters, as HW Modes are preferred as listed, left to right. Selected Channels is a list of numbers associated with the HW Mode Preference. The list can be a comma separated list of individual channels, or ranges of channels (i.e. '1,2,3,4,5,6,7,8,10,11' can be represented as '1-11').
Access Point Zones
An entry in the Access Point Zones scaffold defines the configuration common throughout this site.
Entries in the Access Point Zones scaffold are populated automatically after enabling the monitoring checkbox for a supported WLAN controller Infrastructure Device.
The Enable DFS channels checkbox instructs the Access Points in this Access Point Zone to broadcast at the 5GHz frequencies that are generally reserved for radars. Disabling the Dynamic Frequency Selection (DFS) prevents the use of 5GHz channels 52 - 140.
The 5GHz Channel Width option allows the configuration of channel width for the 5GHz radio for Access Points in this Access Point Zone.
Location
The Location view presents the scaffolds associated with configuring the location services layer of your network.
Location Services
An entry in the Location Services scaffold defines a Location server with which the rXg will use to determine the location of a wireless client.
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 a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
The Type field specifies the type of equipment being configured. Choose the appropriate option from the supported device types drop-down menu.
The Host field is the IP address or domain name of the Location device.
The Subnet mask field is used to enter the subnet mask of the network the location device is on.
The Gateway IP field is used to enter the gateway IP address of the location device.
The API port field is used to set the API port, leave blank for device default.
The Username field sets the device admin username.
The Password field sets the device password, note password will remains the same if left blank.
The API key field sets the device API key.
The Timeout field sets the connection timeout in seconds.
The Areas field sets the location areas managed by this service.
The Location events checkbox will create device location events for notifications recieved from the server if checked.
Location Areas
An entry in the Location Areas scaffold allows the Operator of the rXg to define areas that can then be tied to Location Categories.
The Type field is used to determine if the area is a floor or site.
The Category field if set specifies the category applied to events in this area, unless overridden by a more specific category.
The Parent field sets the parent are which contains this area. Example, a site may be a parent to floor.
The Conference AP's field allows the Operator to add any AP's that should be used for Conferences, this used in conjunction with the conference tool makes it easy to broadcast Conference SSIDs to only the areas where the conference is taking place.
The Conference Ports field allows the Operator to add switch ports that should be used for Conferences.
When configured the Admin Roles field sets the admin roles that will be able to request pending admin transactions from APs in this Location Area.
The Min Gradient and Max Gradient fields allow the operator to override the default heatmap gradiation coloration.
Location Categories
The Areas field allows the Operator of the rXg to assign categories to specific Location Areas , which includes any APs selected when creating the category.
The Access Points field allows the Operator to select specific APs that will be tied to this Location Category.
The Infrastructure Devices field allows the Operator to assign Infrastructure Devices to the Location Category.
Device Locations
The Device Locations scaffold lists the reported location of devices on the network. The Time entry shows the time the record was created. The MAC entry lists the MAC address of the connected device. The Session entry shows the login session for the device. The Account entry lists the account the device is a member of. The Event field shows the event type for record. The Area field shows the Location Area the record belongs to and the Category field shows the Location Category the record is associated with. The Dwell entry displays the amount of time the device has been in a given area. The Last Area and Last Category entries display the previous are and category the device was associated with. The Access Point entry lists the IP and MAC address the device was connected to at the time the entry was created. The SSID field displays the SSID the client device was connected to. The WLAN entry shows the WLAN on the rXg the client device was associated with. The RADIUS Realm entry shows the radius realm the device authenticated against. The Location Device lists the Infdev device providing the location information.
Example Setup
In this example shows the process of setting up location in a MDU.
- Add floorplan to location area.
- Create regions for AP placement.
- Place AP's into regions.
Create Location Categories and add AP's.
Add floorplan to location area.
Navigate to Network::Location and create a new Location Area. The Name field is arbitrary, enter a name. Change the Type field to Floor. Note: by selecting floor it allows the operator to upload a floor plan and this will become the partent for any regions that are created, if Site is selected this will be the parent of the floors. Leave Category on -select- as there are none to select at this time. For the Floorplan field click the Choose File button and select the floorplan image to be used. Set the Floor number field to set the floor number. Leave the Parent field on -select- and hit the Create button.
- Create regions for AP placement.
To create regions click on the Floorplan in the Location Area scaffold, this will open up the map allowing the placement of AP's and Regions.
In the Add a Region section enter a name for the region, pick a color for the region and then click Add Region. This create a region that can be placed on the floorplan. The region can be resized by dragging the bottom right corner.
Drag the region to the desired area on the floor plan, adjust size and click save.
Repeat for each area that needs a region.
- Place AP's into regions.
Select an AP from the Place an Access Point / Senso: dropdown. Click the Drag me button.
This will generate an AP that can be placed on the floor plan, the first AP will go in Unit1.
Drag AP to its placement on the map and click Save.
Repeat this step for each AP that is present on the floorplan.
- Create Location Categories and add AP's.
Create a new Location Category.
The Name field is arbitrary, in this case there will be a Location Category created for each unit, the name will reflect the unit. Select the unit for in the Areas field. Select the AP or APs from the Access Points field. Click Create.
Repeat for each Unit.
The rXg is now configured to start keeping track of Device Locations. In order for this to work at a minimum, radius account packets must be received. The below image shows the WLAN settings for the SSID setup for this example. Note: In this example we have control of the wireless infrastructure creating the WLAN pushed all needed settings, without control the WLAN would need to be configured manually on the wireless infrastructure.
The below image shows the information received in the Device Location scaffold.
Recalibration
In order for location-aware functionality to work as well as possible, setting the right calibration on your floorplan is essential. In order to begin recalibration, click on 'Begin Recalibration' In the floorplan view:
Next, click a point on the map. Often times, a wall or one side of a door frame is a good choice because they are easy to measure, in fact most doors are roughly 1 meter wide.
After you clicked your first point, click your second point
After you clicked your second point, enter the distance between the two points in meters, and click Finish.
Finally just let the floor plan view close on its own and reopen it.
After you re-open the floor plan, the new calibration will be displayed.
WAN
The WAN view presents the scaffolds associated with configuring the wide area network interfaces.
An rXg requires at least one properly configured entry in the uplinks scaffold in order to function. If more than one uplink is configured, the rXg can aggregate and failover WAN uplinks. In addition, the rXg can affine and diversity LAN traffic over the WAN uplinks.
An uplink must be configured with a valid IP address and gateway to function. To use DHCP to obtain an IP address and gateway dynamically, simply check the DHCP checkbox in the uplink record. As an alternative, a static IP address may be manually specified by creating a record in the addresses scaffold and associating the record with an uplink. The gateway for a statically assigned IP block must be manually configured in the uplink record. If the upstream ISP requires PPPoE authentication, configure the ISP supplied credentials into a record of the PPPoE scaffold and associate the record with the uplink.
Ethernet Interfaces
An entry in the ethernet interfaces activates and configures a physical port on the rXg to take part in in networking connectivity.
In most cases, at least two ethernet interfaces must be configured (one for the WAN, one for the LAN). In multiple uplink scenarios, it is common to have one ethernet interface configured for each WAN uplink. It is also possible to use VLANs on a single ethernet interface to configure unlimited WAN and LAN interfaces.
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 port field determines the physical ethernet port that this record will activate and configure.
The media field configures the speed and duplex of the Ethernet port. In most cases, the autoselect setting will automatically negotiate the fastest possible link. Autoselect should also be used if automatic crossover detection is required as most Ethernet hardware will disable automatic crossover if anything other than autoselect is specified as the media type.
If physical link cannot be established, first check the physical cable using an isolation test. If the cable is determined to not be the issue, try setting the ethernet interfaces on both sides of the cable to the same speed and duplex. Note that if a straight cable is connected between two nodes, that cable will need to be replaced with a crossover because automatic crossover detection will be disabled when a media type other than autoselect is specified. In addition, using a lower speed setting and avoiding full-duplex communication may be necessary when the cable is long or does not meet the standards needed for higher speed communication.
The MTU setting configures the maximum transmission unit (frame size) for this interface. By default, most ethernet interfaces support 1500 bytes. Large MTUs may be used in gigabit networks that support jumbo frames to obtain better throughput when transferring large files. Support for jumbo frames must be present throughout the infrastructure in order for larger MTUs to work properly.
The addresses , uplink , VLANs and PPPoE fields link an Ethernet interface to a configuration defined by the specified scaffold. These fields shown here are mainly presented for informational purposes. In most scenarios, an administrator will link the address, uplink, VLAN or PPPoE configuration to the Ethernet interface using the other scaffold.
The backup port field specifies an alternative ethernet interface to assign the addresses , uplink , VLANs and PPPoE configuration settings when this ethernet interface goes down. An ethernet interface is marked as down if it loses link or if all of the ping targets associated with it go offline. The VLANs and Network Addresses associated with an ethernet interface are moved to the backup port when the ethernet interface is marked as down. The backup port mechanism is designed to be used with generic L2 switching. Backup ports should not be used with any LAG/MLT/SMLT/LACP configuration on the connected switch.
The checksum offload , TCP segmentation offload and large receieve offload settings offload the specified processing to the NIC hardware when possible. In some cases this may cause instability and in other cases there are performance benefits.
Uplinks
An entry in the uplinks scaffold declares a specified logical interface as a WAN uplink. At least one uplink must be configured for proper rXg operation. More than one uplink may be configured in link control scenarios when the operator has obtained multiple WAN drains. When multiple uplinks are configured, the rXg can aggregate and failover between uplinks as well as diversify and affine LAN traffic amongst them.
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 priority field determines the order of precedence during failover in a link control scenario. When only one uplink is configured, this field has no effect as there is no uplink to failover to. When multiple uplinks are configured and connection aggregation is enabled, a failure of a link will cause another member of the pool to forward all traffic. If aggregation is not enabled, or all uplinks within a pool have failed, then the uplink with the highest priority amongst all of the remaining uplinks will be used to forward the traffic.
The interface , PPPoE and VLAN drop downs specifies the mechanism by which this uplink will forward traffic upstream. Only one option may be selected for each uplink.
The DHCP checkbox enables the DHCP client for this uplink. The network address, subnet mask and default gateway of this uplink are requested from the DHCP server. If a statically configured IP address is desired, leave this checkbox cleared, create a record in the addresses scaffold and associate it with this uplink.
The gateway IP specifies a statically assigned default gateway for this uplink. The default gateway must be within the IP block defined by the network address associated with this uplink. This field should remain blank if the DHCP checkbox is set.
The upload speed and download speed fields describe the throughput of the uplink.
Network Addresses
An entry in the network addresses scaffold defines an IP block that will be associated with an interface, uplink or VLAN.
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 IP field specifies the IP address using CIDR notation that will be configured on the interface specified. If the address record will be used for configuring multiple addresses on the interface via the span field, the IP field configures the first (lowest) IP address of the range.
The span field specifies the range of IP addresses configured by this address record. The default value of 1 is assumed if this field is omitted. For LAN links, a span of 1 is typical. For WAN links, a span of greater than 1 automatically enables translation pooling in NAT scenarios. In addition, bidirectional network address translation (BiNAT) requires the WAN link to span one additional address for each BiNAT.
PPPoE Tunnels
An entry in the PPPoE tunnels scaffold enables the point-to-point protocol over Ethernetclient to connect with the specified credentials through an Ethernet interface for the purpose of configuring a valid uplink.
The username and password fields specify the credentials for the PPPoE client. The credentials are assigned by the upstream ISP.
The service name is an optional service selector. If the upstream ISP did not provide a specific value, leave this field blank.
The interface field associates this PPPoE tunnel with an Ethernet interface. It is highly recommended that an Ethernet interface associated with a PPPoE tunnel be used exclusively for this purpose. Avoid associating addresses, VLANs, and other entities with an Ethernet interface that is designated for a PPPoE tunnel.
The uplink field associates this PPPoE tunnel with an uplink. To use PPPoE, an uplink must be associated with a record in the PPPoE tunnels scaffold, which in turn, is associated with a Ethernet interface. Do not associate an uplink that has a PPPoE tunnel enabled with the Ethernet interface directly.
DNS Servers
An entry in the DNS servers scaffold specifies an upstream DNS server to use for DNS resolution.
It is highly recommended that at least one upstream DNS servers be configured for network resilience, else the built-in DNS server is used for resolution. Without DNS resolution, no networking services will operate.
Many ISPs will provide DNS server entries. These DNS servers should be configured into this scaffold. In a link control scenario where multiple uplinks from a diverse set of ISPs are configured in parallel, the DNS servers for all of the upstream ISPs should be configured with the appropriate uplink setting selected. In this case, theGoogle Public DNS or OpenDNS servers may be used as backup DNS servers for all uplinks.
The IP field specifies the IP address of the DNS server that is to be used for DNS queries. In most cases, the upstream ISP will provide the IP addresses for the public DNS servers for a specific uplink. If no servers are provided, using the Google Public DNS orOpenDNS is a good alternative.
The uplinks field associates uplinks with the DNS server specified in this record. In many cases, the upstream ISP will have DNS servers that are restricted to their customers so it is important to make sure that the right IP is associated with the proper uplink.
Configure IPV6 to IPV4 Tunnel
In this example we will configure the rXg with an IP tunnel that will allow us to access IPv6 addresses over an existing IPv4 connection. The IPv6 tunnel end point is provided by https://ipv6.he.net after passing a basic certification process. We will need to create an IP Tunnel, an Uplink, a Network Address, and lastly a DHCP pool. To begin navigate to Network::WAN.
First we will create an IP Tunnel.
Give the IP Tunnel a name. The Type field should be set to GIF. Set the Local Interface field to the WAN interface. The Remote IP field is the Server IPv4 Address obtained from he.net. The Tunnel Local CIDR field is the Client IPv6 Address obtained from he.net. The Tunnel Remote IP is the Server IPv6 Address obtained from he.net. Click Create.
Next create a new Uplink, give the uplink a name, priority should be lower than your primary uplinks. Change the IP Tunnel field to the IP Tunnel created in the previous step. Click Create.
Next create a new Network address to create the LAN DHCP addresses that the system will hand out to IPv6 enabled clients. Give the Network addresses a name, select the ethernet interface the addresses will be configured on, and fill out the IP field with the information obtained from HE, in the Routed IPv6 Prefixes section. Note that the address given ends with :: which is invalid so append the IP you want to assign to the system usually 1. Checking the Create DHCP Pool box is optional, for this example setup it will not be checked and we will create the DHCP pool. Click Create.
Next navigate to Services::DHCP and create a new DHCP pool. As long as the last address created was the address from the previous step it will auto fill the fields. It may be a good idea to reduce the scope of the pool by changing the end IP from 2001:470:1f07:210:ffff:ffff:ffff:ffff to 2001:470:1f07:210::ff. Click Create
Now if we SSH into the machine and run ifconfig gif0 we should see our intferface configured with the IPv4 Tunnel addresses as well as the IPv6 Address, and we should be able to ping an IPv6 addressing using ping6 like ping6 google.com.
NAT
The NAT view presents the scaffolds that configure settings to modify the network address translation mechanisms of the rXg.
NAT
Entries in the NAT scaffold configure network address translation between LAN subnets and WAN addresses.
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 addresses and static routes field specify the source LAN subnets for which network address translation will be enabled by this record.
The uplinks field specifies the destination WAN address(es) to which the selected LAN will be network address translated.
The Reverse NAT field specifies that traffic sent via selected Uplink is to be NATd to the first IP of the selected Addresses. This option is primarily used when the upstream ISP routes a block of public IPs to the rXg's primary uplink IP (often assigned via DHCP), and those IPs are assigned to a LAN interface for distribution to clients, but there is a need for outbound traffic from the rXg to always be sourced from the routed block of IPs rather than the DHCP uplink IP.
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.
If no records are present in the NAT scaffold, the rXg will automatically enable NAT from subnets that are configured with RFC 1918 specified private addresses.
Static IPs
An entry in the Static IPs scaffold creates a one-to-one mapping between an IP address within a span associated with an uplink and a private IP address on the LAN . This feature is typically used to give public access to a resource that is configured on a private IP address such as a web server.
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 Source IP field determines the destination of the translation of traffic originating from the Public IP.
The Public IP field specifies the IP address within a span of addresses associated with an uplink that will be translated to the Source IP.
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.
Dynamic BiNAT Pools
An entry in the Dynamic BiNAT Pools scaffold specifies a range of IP addresses that may be dynamically assigned to devices whose account has a Max BiNATs value of 1 or greater, and whose policy is enabled for this Dynamic BiNAT Pool. This feature is typically used to give public access to a resource that is configured on a private IP address such as a web server or a gaming device which requires open incoming firewall ports for proper operation.
The end-user may subscribe to a usage plan which allows Dynamic BiNAT, and may enable BiNAT functionality for specific device(s) by accessing the manage devices page of the portal. The operator may also change the active BiNAT device(s) by editing the account's device list. Care must be given to ensure that the range of addresses configured here is large enough to accomodate the number of devices that are configured for Dynamic BiNAT.
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 Start IP field determines the first IP address of the range of uplink addresses that will be used as the Dynamic BiNAT IP for eligible devices. The IP should fall within a span of addresses associated with an uplink that is associated with the device's link control.
The End IP field specifies the last IP address in the range of uplink addresses that will be used as the Dynamic BiNAT IP for eligible devices. The IP should fall within a span of addresses associated with an uplink that is associated with the device's link control.
The Policies field specifies policies that may utilize this BiNAT Pool. When an associated Policy contains Accounts, a number of IP's specified in the Max BiNATs field of the Account will be assigned to that Account. The end user will be able to configure up to that many DMZ devices through the manage devices page in the captive portal. When an associated Policy contains devices that do not belong to an account, such as from an IP group or MAC group, a BiNAT will be assigned to each device currently connected that belongs to the associated Policy. If no policies are associated with this BiNAT pool, the pool is effectively disabled, and the addresses will be available for regular NAT.
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.
Example BiNAT Deployments
Below are 3 BiNAT deployment examples.
Example 1: Dynamic BiNATs
In this example the operator has configured the rXg to have a block of public IP address that are used for CGNAT and another pool that users can dynamically be assigned a public IP address from that can used as NAT for the account. This IP can be assigned to a specific device (DMZ), and can also be used for UPNP.
First a block of public IP address must be assigned to an interface.
Next we need to configure a BiNAT pool by going to Network::NAT , in this case half the public IP addresses will be used for BiNAT's. The Operator can control which accounts/clients can be assigned a BiNAT by selecting the Policies that can use the pool. In this case only users in the Residents-Premium policy will be able to draw from the pool.
Being in the Residents-Premium policy is not all that is required the account must also be set to allow the use of BiNAT IP address. This is controlled by the Usage Plan the user has purchased. This can be set by going to Billing::Plans. Edit the appropriate Usage Plan and look at the Sessions section of the account. Here the Operator can set the number of Max dedicated IPs , in this example it is set to 1. UPnP has also been selected in this case.
Now users who purchase the Residents-Premium plan will have a BiNAT assigned to their account that all the traffic from their devices will NAT through and their devices can create UPnP port forwads automatically.
Example 2: Static Dedicated BiNATs
In this example the rXg has been configured so that each account gets assigned a BiNAT that is static. First a block of public IP addresses must be configured.
Next the BiNAT pool must be configured to consume the entire block of public IP address, and the appropriate policies must be allowed access to the BiNAT pool. Network::NAT.
The account must also be set to allow the use of BiNAT IP address. This is controlled by the Usage Plan the user has purchased. This can be set by going to Billing::Plans. Edit the appropriate Usage Plan and look at the Sessions section of the account. Here the Operator can set the number of Max dedicated IPs , in this example it is set to 1. By checking the Static dedicated IPs box the NAT IP or IPs are reserved and remain staic for the lifetime of the account. UPnP has also been selected in this case.
In this example each account is assigned a BiNAT address when created, and the IP assigned will remain for the lifetime of the account. This is the equivalent of having a static public IP address.
Example 3: BroadBand On Demand
In this example the rXg has been configured so that each account selects the number of Dedicated IP's (BiNAT addresses) that will be assigned to the account at time of purchase. A block of Public IP address must be configured via Network::WAN.
Next the BiNAT pool must be configured to determine which IP address can be used for dedicated IPs, and the appropriate policies must be allowed access to the BiNAT pool. Network::NAT.
The Usage Plans for this example must be configured to allow the user to pick the number of Dedicated IPs by using the Plan Addons scaffold via Billing::Plans. Here two Plan Addons have been created allowing the user to purchase additional Dedicated Ips and allows them to make them static by purchasing the static IP option.
The above configuration allows the user when purchasing a plan to select how many dedicated IP's they want and can purchase the ability to make them static as well.
NAT Reversal example
Video Configuration Guide and Demonstration
In this example a NAT rule will be created for NAT Reversal, it will be assumed here that the ISP is handing out a private IP address and routing a static block of public IP addresses to the private IP address. Traffic that originates from the WAN IP address of the rXg will be NAT'ted to the first IP address of the public static block on the LAN. What this means is that if a client device were to go to whatismyipaddress it would report the first IP address of the static block on the LAN and not the WAN IP address. Inbound traffic from the Internet destined to the first IP address of the public static block on the LAN is now redirected to the WAN IP address of the rXg. This means that if the operator were to put in their browser the first Public IP address from the static LAN block, they would be getting to the WAN of the system.
To configure this there needs to be a WAN uplink that would usually be a static IP address however it could be DHCP that assigns a static IP, and there needs to be a block of static Public IP addresses routed to the uplink IP. Below is an example Uplink configuration that receives a WAN IP via DHCP.
To configure this with an assigned static WAN IP address, create a new Uplink or edit an existing one. Select the interface. Make sure the DHCP box is unchecked, and enter the gateway IP address. Create or update the uplink.
Next create a new Network Address and assign the IP address to the uplink. Give the Network Address a name, and select the interface, the interface should match the interface of the Uplink. Enter the address to be assigned to the uplink and click create.
Next the Static Block of Public IP address will be created. Create a new Network Address. Give the record a name, select the interface that matches the uplink in this case it is vmx1. Enter the IP address in cidr notation. Only a single IP address is needed here however we can assign more to the system by adjusting the span if needed. Setting the span to 2 in this example would assign the .2 and .3 address to the system. Click Create.
Next navigate to Network::NAT and create a new NATs rule.
Give the record a name, select the Uplink and check the Reverse NAT box. Next select the Network Address created in the previous step and click Create.
With this configuration in place, a device on the LAN that goes to whatismyipaddress.com would report that it's IP address was 192.170.0.1. A device going to https://192.170.0.1/admin would get the Admin GUI of the system, even though the uplinks IP is a private address.
LAN
The LAN view presents the scaffolds associated with configuring the local area network interfaces.
An rXg requires at least one properly configured LAN address in order to function. To configure an IP address on an interface, create a record in the addresses scaffold and associate it with an Ethernet interface record. If the LAN distribution network is connected via an 802.1Q VLAN trunk, create VLAN interfaces using the VLANs scaffold and then associate address records with the VLAN interfaces.
Ethernet Interfaces
An entry in the ethernet interfaces activates and configures a physical port on the rXg to take part in in networking connectivity.
In most cases, at least two ethernet interfaces must be configured (one for the WAN, one for the LAN). In multiple uplink scenarios, it is common to have one ethernet interface configured for each WAN uplink. It is also possible to use VLANs on a single ethernet interface to configure unlimited WAN and LAN interfaces.
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 port field determines the physical ethernet port that this record will activate and configure.
The media field configures the speed and duplex of the Ethernet port. In most cases, the autoselect setting will automatically negotiate the fastest possible link. Autoselect should also be used if automatic crossover detection is required as most Ethernet hardware will disable automatic crossover if anything other than autoselect is specified as the media type.
If physical link cannot be established, first check the physical cable using an isolation test. If the cable is determined to not be the issue, try setting the ethernet interfaces on both sides of the cable to the same speed and duplex. Note that if a straight cable is connected between two nodes, that cable will need to be replaced with a crossover because automatic crossover detection will be disabled when a media type other than autoselect is specified. In addition, using a lower speed setting and avoiding full-duplex communication may be necessary when the cable is long or does not meet the standards needed for higher speed communication.
The MTU setting configures the maximum transmission unit (frame size) for this interface. By default, most ethernet interfaces support 1500 bytes. Large MTUs may be used in gigabit networks that support jumbo frames to obtain better throughput when transferring large files. Support for jumbo frames must be present throughout the infrastructure in order for larger MTUs to work properly.
The addresses , uplink , VLANs and PPPoE fields link an Ethernet interface to a configuration defined by the specified scaffold. These fields shown here are mainly presented for informational purposes. In most scenarios, an administrator will link the address, uplink, VLAN or PPPoE configuration to the Ethernet interface using the other scaffold.
The backup port field specifies an alternative ethernet interface to assign the addresses , uplink , VLANs and PPPoE configuration settings when this ethernet interface goes down. An ethernet interface is marked as down if it loses link or if all of the ping targets associated with it go offline. The VLANs and Network Addresses associated with an ethernet interface are moved to the backup port when the ethernet interface is marked as down. The backup port mechanism is designed to be used with generic L2 switching. Backup ports should not be used with any LAG/MLT/SMLT/LACP configuration on the connected switch.
The checksum offload , TCP segmentation offload and large receieve offload settings offload the specified processing to the NIC hardware when possible. In some cases this may cause instability and in other cases there are performance benefits.
In this example, there is no redundancy as there is only one path between the rxg and all network switches. If the rxg loses connectivity with Switch A, Switch B, C, and D will also lose access.
A slightly better version of the above configuration would be to add a Backup Port so that if the primary link to switch A becomes unusable, a secondary link can be utilized.
Edit the primary interface, select several Ping Targets , then select a Backup Port.
In this example, when Igb3 loses link or all Ping Targets fail to respond, the VLANs and Network Addresses associated with Igb3 are moved to the Backup Port Igb2. Igb3 is marked as down.
However, this still leaves Switch A as a single point of failure. Consider the below topology for a higher level of redundancy.
This feature is not dependent on proprietary protocols and as such will work with most any available switch.
Sample Topology: Redundant Core Switches
Sample Topology: Redundant Gateways and Core Switches
Pseudo Interfaces
VXLAN
VXLAN, or Virtual Extensible LAN, is a network virtualization technology designed to address limitations of traditional VLANs (Virtual Local Area Networks) in large environments. VXLAN tunnels Layer 2 Ethernet traffic over a Layer 3 IP network by wrapping local area network data packets inside IP packets for transport across a larger IP network. VXLAN overcomes the limited number of VLANs supported by traditional methods. It uses a 24-bit identifier, allowing for millions of virtual networks compared to the roughly 4,000 of standard VLANs.
Bridge
The bridge interface allows two or more interfaces to have a connection between them at Layer 2. This essentially combines them into a single logical network segment, allowing devices connected to either interface to communicate directly with each other.
LAGG
LAGG, which can also be referred to as LAG (Link Aggregation Group), stands for Link Aggregation. It's a networking technology that groups multiple physical network interfaces together into a single logical interface. This essentially combines the bandwidth and, in some cases, provides redundancy for network connections.
Multiple Interfaces, One Logical Interface: By aggregating several physical interfaces, LAGG creates a single, high-bandwidth logical interface. This can be beneficial for applications requiring a lot of data transfer, like video streaming or large file transfers.
Increased Bandwidth: The combined bandwidth of all the physical interfaces in the LAGG is available to the logical interface. For instance, if you combine two 1 Gbps interfaces using LAGG, you'd get a logical interface with a potential bandwidth of 2 Gbps.
Redundancy: In addition to increased bandwidth, LAGG can also provide redundancy. If one of the physical interfaces in the LAGG fails, traffic can still be transmitted over the remaining active interfaces. This helps to improve network uptime and fault tolerance.
Protocols: There are different protocols for LAGG interfaces, with the most common one being LACP (Link Aggregation Control Protocol). This protocol negotiates with a compatible switch to automatically bundle the physical interfaces into a LAG. Both the switch and the device using LAGG need to support LACP for this to work.
Other protocols included Failover, Load Balance, Round Robin, and Broadcast.
WireGuard
WireGuard is a streamlined approach to virtual private network (VPN) protocols. It emphasizes three key aspects:
Ease of use: WireGuard is designed to be simpler to set up and use compared to other VPN protocols like OpenVPN. This is achieved by having a lean codebase and focusing on essential functionalities.
High performance: WireGuard prioritizes speed. It uses modern cryptographic techniques and a streamlined approach to achieve faster connection speeds and lower latency compared to traditional VPN protocols.
Security: Despite its simplicity, WireGuard offers robust security. It utilizes state-of-the-art cryptography and keeps the attack surface minimal by design.
SoftGRE
A SoftGRE tunnel is a type of tunneling protocol that uses Generic Routing Encapsulation (GRE) to transport Layer 2 Ethernet traffic over an IP network. In simpler terms, it encapsulates Ethernet data packets within GRE packets, allowing them to be sent across an IP network that wouldn't normally support them.
SoftGRE tunnels are particularly useful for extending WiFi networks. They can be used to connect geographically separated WiFi access points (APs) to a central rXg, creating a seamless network for users.
The following configuration steps provide an example of how to configure the rXg as an endpoint for a SoftGRE tunnel.
- 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.
- Set the Interface type to SoftGRE.
- The Members field indicates where tunneled traffic can egress. In this example, only tagged traffic on VLAN 777 will be accepted. Interfaces can be used for untagged traffic and VLANs will be used for tagged traffic.
- In the SoftGRE Listen Interface you will set where incoming SoftGRE connections will be accepted from. Polices will be used to identify LAN side tunnels and WAN Targets will be used to identify tunnels originating from the WAN.
Vendor Specific Configuration Examples - RUCKUS SoftGRE Tunnel
SoftGRE Tunnel Troubleshooting
Confirm the presence of interface bridges The bridge number will be the same as the VLAN with an extra 1 at the beginning. For example if vlan2000 should be carried over the tunnel, you should also have a bridge12000. In our example, there will also be an additional 0 because the VLAN ID is only 3 digits. VLAN 777 becomes bridge10777.
This can be confirmed via SSH with the following command:
ifconfig | grep bridge10777
Confirm the traffic is flowing over the bridge interface
This can be done by using tcpdump
to confirm that you see unicast traffic over the interface. For example, have a client connect and ping 4.2.2.2.
Continuing the use of bridge10777, I will use the following tcpdump
statement tcpdump -ni bridge10777
and confirm that I can see unicast traffic from my client device.
VLANs
The rXg defines a logical 802.1Q virtual LAN interface for each entry in the VLANs scaffold. A good reference for understanding VLANs and trunk ports is Network Warrior (ISBN 0596101511) by Gary Donahue.
Creating a VLAN implies that the Ethernet interface that is directly associated with it is a VLAN trunk port. The device connected to the Ethernet interface must be similarly configured to accept traffic for the VLAN ID specified in this record.
The Physical Interface drop down associates this VLAN logical interface with an Ethernet interface. A VLAN logical interface presents itself in the same manner as a Ethernet interface for network address configuration and policy management purposes. However, the VLAN must be associated with an Ethernet interface so that it knows what physical port to transmit and receive on.
The Service VLAN drop down associates this VLAN with a Q-in-Q parent VLAN interface. Note: if using Q-in-Q the operator should make sure that VLAN hardware filtering is disabled on the Ethernet Interface by navigating to Network::LAN editing the interface and confirm that the VLAN hardware filtering box is unchecked.
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 VLAN ID is an integer value that is used in the VLAN identifier field of the frames transferred over the physical interface defined by this record. The field is 12-bits in the ethernet frame, making the range of values from 0 to 4096. The 0 value is reserved for native traffic and 1 is used for management by many bridges and switches. In addition, 4095 is reserved by most implementations.
The I-SIDs (Backbone Service Instance Identifier) can be used to identify any virtualized traffic across an 802.1ah encapsulated frame.
The Autoincrement drop down changes how VLANs are configured with regards to the number of subnets. none | single L2 | n tags=1 will result in a single VLAN being associated to a single subnet or subnets. per-subnet | auto-increment L2 w/L3 | n tags = subnets / ratio means the number of VLANs that will be configured is the number of Subnets divided by the ration. With a Ratio of 1 and tied to a Network Address that has 32 subnets, 32 VLANs will be configured. With a Ratio of 2 and a Network Address with 32 subnets, 16 VLANs will be configured (32 / 2 = 16).per-IP | auto-increment L2 over split L3 via BNG | n tags = (usable IPs / ratio)means if we have a Network Address configured with 32 usable IP addresses the number of VLANs that will be configured is the number of IP address divided by the ratio. Given a Network Address with 32 usable IP addresses and a Ratio of 1, 32 VLANs will be configured. If the Ratio is set to 2, 16 VLANs will be configured (32 / 2 = 16).
The Ratio field is the number of autoincrement subnets or usable IPs in each VLAN tag.
The MAC Override allows the operator to adjust the MAC address(es) assigned to each VLAN interface created based on this VLAN configuration. The MAC address assigned to each VLAN will be the MAC Override incremented for each VLAN interface created. The first VLAN interface created will use the value of MAC Override. For each additional VLAN created, the value will be incremented by 1. For example a MAC Override of ff:ff:fe:00:00:1a with a vlan tag of 10 will result in a MAC address of ff:ff:fe:00:00:1a being assigned to the vlan10 interface. When using autoincrement, vlan11 will be assigned ff:ff:fe:00:00:1b , vlan12 will be assigned ff:ff:fe:00:00:1c , etc.
The addresses field associates one or more network addresses with this VLAN logical interface. All interfaces, including logical VLAN interfaces, must have one or more network addresses associated with them in order for them to pass traffic.
The Switch Port Profiles field allows the operator to associate the VLAN(s) to a switch port profile that will automatically configured the VLAN(s) to the switch ports attached to the profile.
The WLANs field allows the operator to associate the VLAN(s) to a WLAN.
The Conference options field allows the operator to associate the VLAN(s) to a conference record so the VLAN(s) can be used when created a conference via the Conference Tool.
Network Addresses
An entry in the network addresses scaffold defines an IP block that will be associated with an interface, uplink or VLAN.
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 IP field specifies the IP address using CIDR notation that will be configured on the interface specified. If the address record will be used for configuring multiple addresses on the interface via the span field, the IP field configures the first (lowest) IP address of the range.
The span field specifies the range of IP addresses configured by this address record. The default value of 1 is assumed if this field is omitted. For LAN links, a span of 1 is typical. For WAN links, a span of greater than 1 automatically enables translation pooling in NAT scenarios. In addition, bidirectional network address translation (BiNAT) requires the WAN link to span one additional address for each BiNAT.
Examples using Autoincrement
1. Autoincrement with 1:1 VLAN per subnet (MDU)
In this example the VLAN is configured per-subnet with a ratio of 1, this means that each subnet will have it's own VLAN tag. The number of VLANs used will be the number of subnets divied by the ratio. For this example there will be 128 /24 subnets tied to the VLAN which will result in 128 VLANs.
Create a new VLAN Interface , give it a name, select the Physical Interface the VLANs will be tied to. Set the VLAN IDs field to first VLAN to be used. Autoincrement is set to per-subnet , and Ratio is set to 1. If the Network Address is created already it can be selected, in this case it does not, click Create.
Next create a new Network Address , give it a name. Under the Interface section set the Ethernet field to select, and the VLAN field to the VLAN created in the previous step. Set the IP field to the desired starting network address using CIDR notation. Next set the Autoincrement field to the desired number of subnets to create, in this case it will be set to 128. Check the Create DHCP Pool box and then click Create.
Now there are 128 /24 subnets that have been created (10.0.0.1/24-10.0.127.1/24), and 128 VLANs have been configured (100-227) tied sequentially to the subnets.
2. Autoincrement with more than 1 subnet per VLAN
In this example the configuration will put more than 1 subnet into each VLAN. The number of VLANs in this case will be the number of subnets divided by the ratio. In this example there are 64 /30 subnets and the ratio will be set to 4. In this configuration there will end up being 16 VLANs configured.
Create a new VLAN Interface , give it a name, select the Physical Interface the VLANs will be tied to. Set the VLAN ID's field to the first VLAN to be used. Autoincrement is set to per-subnet , and Ratio is set to 4. If the Network Address is created already it can be selected, in this case it does not, click Create.
Next create a new Network Address , give it a name. Under the Interface section set the Ethernet field to select, and the VLAN field to the VLAN created in the previous step. Set the IP field to the desired starting network address using CIDR notation. Next set the Autoincrement field to the desired number of subnets to create, in this case it will be set to 64. Check the Create DHCP Pool box and then click Create
With this configuration there are 64 /30 subnets with 4 subnets per VLAN. 64(subnets) / 4(Ratio) gives us a total of 16 VLANs.
3. BNG with many VLANS inside a single subnet.
The autoincrement BNG feature enables a single subnet to be divided amongst a large number of VLANs. Autoincrement BNG maximizes public address space distribution efficiency. A public /24 CIDR block would typically need to be divided into 64 /30 CIDRs for distribution amongst subscribers. Each of the /30 CIDRs would then be assigned to a unique layer 2 microsegment. Thus a /24 CIDR block would typically support 64 subcscribers. This is an inefficient use of public IPv4 address space.
Network | VLAN |
---|---|
76.77.78.0/30 | VLAN 1000 |
76.77.78.4/30 | VLAN 1001 |
76.77.78.8/30 | VLAN 1002 |
â‹® | â‹® |
76.77.78.248/30 | VLAN 1062 |
76.77.78.252/30 | VLAN 1063 |
The autoincrement BNG feature enables efficient distribution of public static IPv4 24 CIDR blocks. For example, a /24 CIDR block can support 253 subscribers where each subscriber is microsegmented onto their own unique layer two on the distribution infrastructure. It may help to think of this as autoincrementing VLAN assignment via /32s instead of /30s. The difference is that all of the /32s share a single gateway that is accessible from all VLANs. In reality the BNG autoincrement mechanism enables distribution of the addresses on a /24 subnet to ensure client compatibility. This enables efficient use of address space while enforcing true segmentation through a universally compatible standards-based approach.
Network | VLAN |
---|---|
76.77.78.2/24 | VLAN 1000 |
76.77.78.3/24 | VLAN 1001 |
76.77.78.4/24 | VLAN 1002 |
â‹® | â‹® |
76.77.78.253/24 | VLAN 1251 |
76.77.78.254/24 | VLAN 1252 |
In the example below, autoincrement BNG microsegments each usable IP address in 76.77.78.0/24 onto a unique VLAN. VLAN 3002 on igb3 is configured with the first address of the CIDR 76.77.78.1/24 as if the entire CIDR were configured onto VLAN 3002. All of the usable IP addresses of CIDR 76.77.78.0/24 (76.77.67.2/24 to 76.77.78.254/24 inclusive) would normally share the same VLAN 3002. However with autoincrement BNG enabled, the usable IPs are spread across VLANs 3002 to 3254 inclusive.
Autoincrement BNG is unique in that it allows all client devices to share the same default gateway despite being microsegmented at layer 2. In this example, all client devices in VLANs 3002 to 3254 inclusive use 76.77.78.1/24 as their the default gateway. Sharing a single layer 3 default gateway IP address amongst a large number of layer 2 microsegmented clients dramatically improves the efficiency of IP address consumption.
It is important to note that only VLANs 3002 to 3254 inclusive are usable on igb3 when autoincrement BNG is enabled on igb3. It is impossible to assign additional VLANs to igb3 that fall outside of the BNG range as this would interfere with the autoincrement BNG functionality in the configuration described above. An operator may use Q-in-Q if they wish to configure both both BNG and non-BNG VLANs on the same physical interface. This is what we will discuss next.
In this example a single service VLAN (SVLAN 100) will be created and used as the parent VLAN that will contain many client VLANs (CVLANs 1000 to 1352 inclusive). Putting VLAN tags inside other VLAN tags is referred to as a Q-in-Q network architecture.
First create a new VLAN Interface that will be the parent VLAN that will contain the many VLANs. Give it a name. Select the Phyiscal Interface the VLAN will be attached to. Set the VLAN IDs that will be the parent VLAN. Set Autoincrement to none. If there are any Switch Port Profiles configured they can be added here to add the VLAN to any necessary ports. Click Create.
Next configure the VLAN pool that will be tied to the parent VLAN created in the previous step, these VLANs will be tied to IP address in that will be created in the next step as needed. Create a new VLAN Interface and give it a name. The Physical Interface should be unselected and the Service VLAN should be set to the Parent VLAN created in the previous step. The VLAN IDs should be set to the first VLAN to be used. Autoincrement should be set to per-ip , Ratio is set to 1. There is no need to select a Switch Port Profile as these VLANs will not be seen by the switch. Click Create.
Next create a new Network Address , give it a name. Under Interface the Ethernet field should be set to -select- , and the VLAN field should be set to the VLAN created in the previous step. Enter the IP address in CIDR notation in the IP field. The Autoincrement and Span field should be set to 1. Checking the Create DHCP Pool box will automatically create a DHCP pool for the addresses. Click Create.
With this configuration we have a VLAN (VLAN 1000), that contains our BNG VLANs (VLANS 100-352) which allows for the BNG VLANs to be assigned individually to a single IP within the BNG Addresses that were configured. Multiple IPs can be assigned the same VLAN within the address pool as needed and each assignment only consumes a single IP instead of a minimum of 4.
The use of the Q-in-Q network architecture allows a single physical interface to be used with multiple autoincrement BNG interfaces as well as static or dynamically configured VLANs. For example:
Here we see multiple BNG interfaces are created to support distinct downstream distribution equipment. We also see that there is an additional SVLAN that is dedicated for management infrastructure. The standards based nature of the autoincrement BNG approach enables unparalleled flexibilty and diversity. Any VLAN-aware distribution equipment, wireline or wireless, may participate in an autoincrement BNG deployment. In fact, it is even possible to have a single distribution infrastructure composed of equipment from multiple vendors and even mixing different forms of technology. A single installation may use BNG to efficiently distribute public IP addresses across DSL, GPON, DOCSIS, fixed wireless and PLTE all within the same deployment.
Routing
The routing view presents the scaffolds that configure settings to that control the static and dynamic entries into the rXg routing table.
The routing table of an rXg governs where packets are forwarded based on their desired destination. In a basic rXg installation where end-users are L2 connected to the LAN side of the rXg which is in turn connected to a single uplink, the routing table that is automatically created by the rXg is sufficient. In this case, no changes should be made to any of the scaffolds on the routing view.
If the rXg is deployed with a L3 routed distribution network for end-user access, then the rXg must be informed of all connected networks in order to properly route traffic and deliver forced browser redirection. This is typically accomplished by creating static routes for the various subnets that are connected behind L3 routers on the LAN side of the rXg.
The rXg supports distribution and integration of routes via RIP primarily for the purposes of simplifying cluster management. When an rXg cluster is deployed and routing between end-users on different nodes is desired, the rXgs must be informed as to all of the subnets that are behind the various cluster nodes. In addition, the rXg may broadcast router discovery responses to LAN nodes so that they may build up the internal routing tables on LAN nodes. This is particularly useful for LAN nodes that are locally and remotely accessible servers as this provides a simple mechanism for dynamic failover between multiple cluster nodes.
Static Routes
An entry in the static routes scaffold creates an entry in the IP routing table of the rXg.
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 destination field configures the CIDR block for which a specific gateway is needed.
The gateway is the IP address of the next hop router for the CIDR block specified in the destination field.
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.
RIP
The RIP scaffold controls the behavior of the rXg with respect to RFC 1058 and RFC 2453 router information protocol messages. The rXg may be configured to broadcast route advertisements as well as accept RIP announcements from other routers.
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 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 transmit RIP checkbox enables the broadcast of route advertisements to locally connected networks. When this box is checked, the rXg will make RIP announcements
The receive RIPv1 and receive RIPv2 checkboxes enable the rXg to receive RIPv1 and RIPv2 route advertisements respectively.
The RIPv2 password field configures the shared security credential that will be used when sending and receiving RIPv2 announcements.
The trusted gateways field is where the operator specifies the routers from which RIP announcements will be accepted. In order to prevent injection of false routers, it is required that one or more trusted gateways be specified in order to receive RIP announcements.
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.
Wired
The Wired view presents the scaffolds associated with configuring the wired distribution layer of your network, and monitoring/configuring the switch ports throughout your infrastructure.
Switches
An entry in the switches scaffold defines a piece of switching equipment with which the rXg will communicate for the purpose of effecting dynamic VLAN changes when necessary due to a policy shift for a device on the network.
When a device's VLAN assignment has changed due to a policy shift, the rXg will connect to the switch associated with the device's RADIUS realm via the protocol specified in the configuration, and force a disconnect/reconnect, which will reinitiate the RADIUS authentication process, thereby resulting in the new VLAN assignment being applied to the client device.
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 device section specifies information of equipment being configured. Fields with bold text are required. Choose the appropriate option from the supported device types drop-down menu.
Enabling the Monitoring checkbox results in the rXg attempting to import and synchronize Switch Ports from the device, as well as perform ping monitoring of the switch itself, and collect CPU and Memory statistics, where possible.
The SNMP community field specifies the SNMP community string that will be used when attempting to gather CPU and/or Memory information, as well as to collect Switch Port utilization/error/discard data for graphing.
The Switch Fabric field assigns a switch fabric profile to this switch. The Loopback IP , System name , and SPB-m nickname fields must be provided when assigning a switch fabric profile. After supplying the necessary information, the Config sync status link becomes available in the scaffold.
For switches that support configuration management, the Config sync status column contains a link that allows the operator to access bootstrap instructions and enable synchronization.
When bootstrapping a new switch, the operator may retrieve bootstrap commands that will bring a factory default switch or wireless controller into the necessary state to participate in the fabric network, which may be copy/pasted into a console session on the device.
After initial bootstrapping and network connectivity is established, the operator may download a running configuration backup or compare the current running configuration to the expected configuration, based on the associated configuration elements. If changes are needed, they may be pushed to the switch. After successfully synchronizing manually the first time, future configuration changes will be pushed to the device whenever relevant configuration changes are made in the database.
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.
Switch Fabric
An entry in the Switch Fabric scaffold defines the fabric area of a 802.1aq Shortest Path Bridging-MAC (SPB-m) deployment. All participating fabric switches share the common configuration found here. In addition, each participating fabric switch should have an Infrastructure Device defined with the necessary SPB-m configuration specific to that device.
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 Management I-SID field specifies the I-SID that will be associated with the Management VLAN for management traffic. The Management VLAN is configured per device, under the Switches scaffold.
The Manual area field specifies the IS-IS area that will be used within this fabric in the format: xx.xxxx (ex: 10.0001)
The Primary B-VLAN and Secondary B-VLAN fields indicate the VLANs which will be used for passing encapsulated traffic between participating fabric switches on switch ports designated as NNI ports. These VLANs should be unused elsewhere in your infrastructure.
Switch Ports
Entries in the Switch Ports scaffold are created automatically by enabling the Monitoring checkbox on a supported switch's Infrastructure Device. Ports are imported and speed, packet, error and discard rates are gathered via SNMP and made graphable for each switch port.
The name field represents the port's identification in the switch, and should not be changed.
The NNI Port designates this port as a Network-to-Network Interface. This option must be enabled for any port where two fabric-enabled switches interconnect.
The speed in bps field represents the port's maximum physical speed in bits per second.
Switch Port Profiles
Entries in the Switch Port Profiles scaffold define the behavior of downstream wired infrastructure device ports. Switch port profiles enable an operator to manage virtually unlimited switch ports, without configuring them individually.
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 Default checkbox, declares the selected switch port profile as the default for any newly imported switches
The Move Ports checkbox, if selected, will move ports associated with a different default profile to a profile upon save. This should be used in conjunction with the Default checkbox.
The Ports field defines individual switch ports to associate with this profile.
The Native VLAN field is used to define the untagged VLAN that ports associated to a profile should use.
The Shutdown checkbox declares ports associated to this profile to be disabled.
The VLANs field defines the VLANs that should be tagged on ports associated with a profile.
The RADIUS drop-down menu can be used to enable 802.1x or MAC Authentication Bypass, on ports associated to a profile.
The native I-SID specifies the network that untagged traffic from this port should be placed into when building a Fabric configuration script.
The NNI Port designates this port as a Network-to-Network Interface. This option must be enabled for any port where two fabric-enabled switches interconnect.
Wireless
The Wireless view presents the scaffolds associated with configuring the wireless distribution layer of your network, and monitoring/configuring the access points throughout your infrastructure.
WLAN Controllers
An entry in the WLAN controllers scaffold defines a piece of wireless equipment with which the rXg will communicate for the purpose of effecting dynamic VLAN changes when necessary due to a policy shift for a device on the network.
When a device's VLAN assignment has changed due to a policy shift, the rXg will connect to the WLAN controller associated with the device's RADIUS realm via the protocol specified in the configuration, and force a disconnect/reconnect, which will reinitiate the RADIUS authentication process, thereby resulting in the new VLAN assignment being applied to the client device.
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 device field specifies the type of equipment being configured. Choose the appropriate option from the supported device types drop-down menu.
The enable telemetry boolean completely controls whether the rXg will attempt to receive and process telemetry data at all.
The Instrument from Telemetry checkbox results in the rXg using telemetry data to instrument the Access Points and Wireless Clients for this controller, instead of the regular API integration. If telemetry is enabled, the rXg will always instrument radio and client data, regardless of whether instrument from telemetry is enabled.
Enabling the Monitoring checkbox results in the rXg attempting to import and synchronize Access Points from the device, as well as perform ping monitoring of the Infrastructure Device itself, and collect CPU and Memory statistics, where possible.
The SNMP community field specifies the SNMP community string that will be used when attempting to gather CPU and/or Memory information, or Access Point data from WLAN controllers where an API is not available.
The NB portal password and NB portal usernames are used when executing API calls against RUCKUS's northbound portal interface. These must correlate with what is configured in the controller.
The Telemetry username and Telemetry password are used when authenticating an MQTT session with this WLAN Controller. These must correlate with what is configured in the controller's northbound data streaming subscriptions.
Vendor Specific Configuration Examples
For Infrastructure Devices which support configuration management, the Config sync status column contains a link that allows the operator to access bootstrap instructions and enable synchronization.
When enabling automatic WLAN controller configuration management, the operator should ensure that the timezone and country code set in the Device Options scaffold are accurate as they will be used when configuring wireless infrastructure.
After initial bootstrapping and network connectivity is established, the operator may download a running configuration backup or compare the current running configuration to the expected configuration, based on the associated configuration elements. If changes are needed, they may be pushed to the controller. After successfully synchronizing manually the first time, future configuration changes will be pushed to the device whenever relevant configuration changes are made in the database.
Vendor Specific Configuration Examples
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.
Piglet Sensor
Piglets are small, low-cost, raspberry pi based, sensors that can be used for a variety of purposes. Adding a WLAN Controller with a device type of "Piglet" and a host address of "127.0.0.1" in this scaffold will allow the piglet sensors to discover the rXg for adoption. Click Here to access the piglet documentation.
WLANs
An entry in the WLANs scaffold defines a wireless network that you wish to deploy on a supported WLAN controller.
The SSID field specifies the WLAN SSID that will be broadcast and visible to users.
The Encryption selection specifies the encryption algorithm which will be used for this WLAN.
The Authentication selection specifies the type of authentication that should take place in order for users to join the network. In order for Dynamic VLANs to be assigned, authentication must utilize MAC Authentication Bypass or one of the 802.1X methods.
The Default VLAN field specifies the VLAN that users should be placed into, assuming it is not overriden by Dynamic VLAN behavior.
The Tunnel checkbox instructs access points to build a tunnel to the controller or some other location, depending on the vendor, instead of locally bridging the client traffic.
Application Examples: - RUCKUS SoftGRE Tunnel
The Enabled checkboxes allow the operator to enable or disable a WLAN for a particular radio across all profiles where it is utilized.
Dynamic VLANs require the association of at least one VLAN record which is tied to a RADIUS Realm.
The RADIUS Accounting checkbox instructs the Access Point to send accounting information to the RADIUS server as users join, use, and leave the network.
The Access Point Profiles selection specifies which Profiles should include this WLAN.
Access Point Profiles
An entry in the Access Point Profiles scaffold defines a set of common configuration parameters to be applied to a set of Access Points.
The Default checkbox indicates that this Profile will be the default Profile for this Infrastructure Device. Any Access Point which has not been explicitly assigned to a Profile will be placed into this Profile.
The WLANs association defines whoch WLANs will be broadcast on Access Points that fall into this Profile.
The Access Points association allows the operator to explicitly assign a profile to one or more Access Points. Selected Access Points which do not belong to the Infrastructure Device that the Profile is assigned to will be automatically deselected upon saving.
The Management VLAN field specifies which VLAN the Access Points in this profile will use to attempt to obtain an IP address via DHCP.
The 2.4GHz Data Rates and 5GHz Data Rates fields allow the operator to restrict the types of devices that may join the network to only those supporting a specific subset of data rates. By default, 802.11b rates are disabled to improve network performance.
The 2.4GHz Antenna Gain and 5GHz Antenna Gain fields allow the operator to specify antenna gain values (in dBi) that will be applied to Access Points which use external antennas.
The Outdoor APs checkbox instructs the system to enable or disable outdoor power and channel tables for the radios in order to be compliant with regulatory rules.
Access Points
Entries in the Access Points scaffold are created automatically by enabling the Monitoring checkbox on a supported wireless controller's Infrastructure Device. Status and statistics are gathered on an ongoing basis via API and/or SNMP.
After creation, the operator may reassign an Access Point's Access Point Profile in order to control the WLAN and radio settings applied to it. Access Point details are updated on a regular basis via background interaction with the Infrastructure Device.
Access Point Radios
Entries in the Access Point Radios scaffold are created automatically by enabling the Monitoring checkbox on a supported wireless controller's Infrastructure Device. Status and statistics are gathered on an ongoing basis via API and/or SNMP.
Access Point Radio Profiles
Entries in the Access Point Radio Profiles scaffold can be assigned to WLANS in the Access Point Profiles scaffold. The HW Mode Preference field ia a comma separated listing of supported radio type, 'A' (5 Ghz, 802.11 A and 802.11 AC), 'B' (2.4 Ghz 802.11 B), or 'G' (2.4 Ghz 802.11 G). The order matters, as HW Modes are preferred as listed, left to right. Selected Channels is a list of numbers associated with the HW Mode Preference. The list can be a comma separated list of individual channels, or ranges of channels (i.e. '1,2,3,4,5,6,7,8,10,11' can be represented as '1-11').
Access Point Zones
An entry in the Access Point Zones scaffold defines the configuration common throughout this site.
Entries in the Access Point Zones scaffold are populated automatically after enabling the monitoring checkbox for a supported WLAN controller Infrastructure Device.
The Enable DFS channels checkbox instructs the Access Points in this Access Point Zone to broadcast at the 5GHz frequencies that are generally reserved for radars. Disabling the Dynamic Frequency Selection (DFS) prevents the use of 5GHz channels 52 - 140.
The 5GHz Channel Width option allows the configuration of channel width for the 5GHz radio for Access Points in this Access Point Zone.
Location
The Location view presents the scaffolds associated with configuring the location services layer of your network.
Location Services
An entry in the Location Services scaffold defines a Location server with which the rXg will use to determine the location of a wireless client.
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 a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
The Type field specifies the type of equipment being configured. Choose the appropriate option from the supported device types drop-down menu.
The Host field is the IP address or domain name of the Location device.
The Subnet mask field is used to enter the subnet mask of the network the location device is on.
The Gateway IP field is used to enter the gateway IP address of the location device.
The API port field is used to set the API port, leave blank for device default.
The Username field sets the device admin username.
The Password field sets the device password, note password will remains the same if left blank.
The API key field sets the device API key.
The Timeout field sets the connection timeout in seconds.
The Areas field sets the location areas managed by this service.
The Location events checkbox will create device location events for notifications recieved from the server if checked.
Location Areas
An entry in the Location Areas scaffold allows the Operator of the rXg to define areas that can then be tied to Location Categories.
The Type field is used to determine if the area is a floor or site.
The Category field if set specifies the category applied to events in this area, unless overridden by a more specific category.
The Parent field sets the parent are which contains this area. Example, a site may be a parent to floor.
The Conference AP's field allows the Operator to add any AP's that should be used for Conferences, this used in conjunction with the conference tool makes it easy to broadcast Conference SSIDs to only the areas where the conference is taking place.
The Conference Ports field allows the Operator to add switch ports that should be used for Conferences.
When configured the Admin Roles field sets the admin roles that will be able to request pending admin transactions from APs in this Location Area.
The Min Gradient and Max Gradient fields allow the operator to override the default heatmap gradiation coloration.
Location Categories
The Areas field allows the Operator of the rXg to assign categories to specific Location Areas , which includes any APs selected when creating the category.
The Access Points field allows the Operator to select specific APs that will be tied to this Location Category.
The Infrastructure Devices field allows the Operator to assign Infrastructure Devices to the Location Category.
Device Locations
The Device Locations scaffold lists the reported location of devices on the network. The Time entry shows the time the record was created. The MAC entry lists the MAC address of the connected device. The Session entry shows the login session for the device. The Account entry lists the account the device is a member of. The Event field shows the event type for record. The Area field shows the Location Area the record belongs to and the Category field shows the Location Category the record is associated with. The Dwell entry displays the amount of time the device has been in a given area. The Last Area and Last Category entries display the previous are and category the device was associated with. The Access Point entry lists the IP and MAC address the device was connected to at the time the entry was created. The SSID field displays the SSID the client device was connected to. The WLAN entry shows the WLAN on the rXg the client device was associated with. The RADIUS Realm entry shows the radius realm the device authenticated against. The Location Device lists the Infdev device providing the location information.
Example Setup
In this example shows the process of setting up location in a MDU.
- Add floorplan to location area.
- Create regions for AP placement.
- Place AP's into regions.
Create Location Categories and add AP's.
Add floorplan to location area.
Navigate to Network::Location and create a new Location Area. The Name field is arbitrary, enter a name. Change the Type field to Floor. Note: by selecting floor it allows the operator to upload a floor plan and this will become the partent for any regions that are created, if Site is selected this will be the parent of the floors. Leave Category on -select- as there are none to select at this time. For the Floorplan field click the Choose File button and select the floorplan image to be used. Set the Floor number field to set the floor number. Leave the Parent field on -select- and hit the Create button.
- Create regions for AP placement.
To create regions click on the Floorplan in the Location Area scaffold, this will open up the map allowing the placement of AP's and Regions.
In the Add a Region section enter a name for the region, pick a color for the region and then click Add Region. This create a region that can be placed on the floorplan. The region can be resized by dragging the bottom right corner.
Drag the region to the desired area on the floor plan, adjust size and click save.
Repeat for each area that needs a region.
- Place AP's into regions.
Select an AP from the Place an Access Point / Senso: dropdown. Click the Drag me button.
This will generate an AP that can be placed on the floor plan, the first AP will go in Unit1.
Drag AP to its placement on the map and click Save.
Repeat this step for each AP that is present on the floorplan.
- Create Location Categories and add AP's.
Create a new Location Category.
The Name field is arbitrary, in this case there will be a Location Category created for each unit, the name will reflect the unit. Select the unit for in the Areas field. Select the AP or APs from the Access Points field. Click Create.
Repeat for each Unit.
The rXg is now configured to start keeping track of Device Locations. In order for this to work at a minimum, radius account packets must be received. The below image shows the WLAN settings for the SSID setup for this example. Note: In this example we have control of the wireless infrastructure creating the WLAN pushed all needed settings, without control the WLAN would need to be configured manually on the wireless infrastructure.
The below image shows the information received in the Device Location scaffold.
Recalibration
In order for location-aware functionality to work as well as possible, setting the right calibration on your floorplan is essential. In order to begin recalibration, click on 'Begin Recalibration' In the floorplan view:
Next, click a point on the map. Often times, a wall or one side of a door frame is a good choice because they are easy to measure, in fact most doors are roughly 1 meter wide.
After you clicked your first point, click your second point
After you clicked your second point, enter the distance between the two points in meters, and click Finish.
Finally just let the floor plan view close on its own and reopen it.
After you re-open the floor plan, the new calibration will be displayed.
Services
All IP-data networks must provide several core services in order for end-users to establish connectivity. The vast majority of IP-data networks use DHCP for provisioning end-user IP addresses. Thus a DHCP server is a requirement for almost every IP-data network. DHCP server responses include DNS server information. Most IP-data networks incorporate a local, caching DNS server, to improve network performance. Furthermore, information security is another critical aspect of the contemporary IP-data networks. One commonly deployed service to help increase the trustworthiness of the network is an IPsec VPN concatenator. Many IP-data network also incorporate network time (NTP) and SNMP services to ease administration.
Revenue generating networks must deliver several additional services in addition to which most other IP-data networks must provide. If a captive portal is used, then a web application server must be present on the RGN. If the captive portal is to incorporate advertising, an advertising proxy and rotation server is needed. Email broadcasts, transparent web proxies and many other possibilities exist. In many cases, the profitability of the RGN is directly related to the availability and provisioning of the network core services.
The rXg incorporates all of the core services needed to operate a revenue generating network. The services menu enables the operator to access the views needed to configure core services integrated into the rXg.
Services Dashboard
The services dashboard presents an overview of the current status and configured settings for the various core services executing on the rXg.
The left column presents dialogs depicting summaries of the latest instrumentation gathered from the DHCP server.
The top dialog in the left column displays statistical information about the DHCP pools offered by the DHCP server. Next to the name of the pool, the current number of free and used leases is displayed. The right column displays the maximum number of leases that may be in use simultaneously. This dialog is extremely useful in determining if the DHCP pool is configured in a way that makes it capable of serving the entire end-user population.
The bottom dialog in the left column displays the four latest DHCP leases that were issued by the DHCP server. The IP address issued is listed along with the MAC address and DHCP client ID (if the client transmitted one in the request). This dialog is very useful for quickly tracking down problematic end-users who have recently joined the network. First call end-user support personnel will find the information presented in this dialog very useful in identifying and isolating end-users with connectivity problems.
The right column presents graphs describing the recent load of various core rXg services.
The first graph in the right column presents the recent average number of DHCP leases.
The second graph in the right column presents the recent average number of VLAN tag assignments.
The last graph in the right column presents the recent average number of web server hits. The web server hit count is determined by the number of end-users hitting the captive portal web application, typically as a result of forced web browser redirection. Keep in mind that the default interstitial advertising methodology uses the captive portal to deliver the ad content as well.
The dialog presented at the bottom of the left column displays a dashboard of status lights for the various services offered by the rXg. A red light means the service is currently offline or disabled. A green light means that the service is currently running. This dialog is the quickest way to obtaining a first order understanding of why a particular rXg subsystem is misbehaving when troubleshooting new service deployment scenarios. Clicking on the light will take you to a relevant view for configuring the service. This dialog also displays the current instantaneous rate of web server, web proxy and HTML injection hits. This is very useful for comparing the current rate with the rates presented in the graphs to see where the current load of the rXg fits in the overall picture of recent load.
DHCP
The DHCP view presents the scaffolds associated with configuring the DHCP server and DHCP relay features of the rXg.
The rXg integrates a fully featured DHCP server capable of meeting the needs of nearly any imaginable environment. By default, the rXg DHCP server responds to all DHCP requests on the LAN with a temporary address assignment from within a pool. This behavior may be modified and augmented via the scaffolds presented on this view to deliver a broad spectrum of possible responses.
To enable the rXg integrated DHCP server, the operator must create a DHCP pool that falls within the CIDR of an address that is on the LAN of the rXg. An address is considered to be on the LAN of the rXg if the address is associated with an Ethernet interface , VLAN or is the destination in a static route.
The CIDR of the address from which the pool draws IP addresses from automatically determines the DHCP server listening interface as well as the subnet mask and default route that is presented to the client.
For example, given an rXg that has the following addresses :
- Ethernet Interface en1: 192.168.5.1 / 24
- VLAN 3800: 172.16.16.1 / 22 If a DHCP pool for with a range of 192.168.5.100 to 192.168.5.200 is created, the rXg integrated DHCP server will listen on en1 for DHCP requests in the native VLAN and respond with:
- IP address in range 192.168.5.100 to 192.168.5.200
- subnet mask 255.255.255.0
- default gateway 192.168.5.1 Similarly, if a pool with a range of 172.16.23.1 to 172.16.28.255 is created, then DHCP requests present on VLAN 3800 will see a response of:
- IP address in range 172.16.23.1 to 172.16.28.255
- subnet mask 255.255.240.0
- default gateway 172.16.16.1
Many networks combine DHCP assigned addresses with manually assigned static addresses. Use the pools scaffold to control the range of addresses issued by the rXg. It is extremely important to ensure that network administrators manually configure statically assigned addresses correctly to prevent overlap. It is also suggested that VLANs be used for L2 segregation of machines with statically assigned addresses from those pulling from DHCP in order to prevent IP address collisions. Alternatively, the network operator may choose to use DHCP fixed hosts in lieu of statically assigned addresses to achieve the same goal.
In most networks, there are some devices which should obtain the same IP address every time a request is made. A common occurrence of this is when a Static IP has been configured for a device that is using DHCP. To ensure connectivity, the BiNAT'ed device must have a static IP address or must be established as a fixed host. It is important to make sure that fixed hosts are assigned IP addresses that are outside of the ranges specified by the pools
Two, non-overlapping pools may also be configured for the same Ethernet interface or VLAN. Given the example rXg network address configuration above, 172.16.23.1 to 172.16.28.1 and 172.16.20.1 to 172.16.22.255 may both be configured as pools simultaneously. By default, requests originating from VLAN 3800 will draw addresses from both pools. This behavior is usually modified through the use of classes and match rules.
Match rules may be used to differentiate between requests originating from the same physical or logical media. For example, match rules may be used to associate devices presenting DHCP client identifiers containing a specific prefix with a class. Another common use of match rules is to place all devices presenting a MAC address from a specific vendor into a class.
A class may be used to determine the pool from which the requesting device acquires an address. This is useful for IP-based policy management as certain devices may be placed into specific ranges of IP addresses which can have different policies associated with them. In addition, different pools may have different DHCP options. For example, pools may have different maximum lease times, DNS servers, default routes, etc.
If there is a LAN CIDR block configured on the rXg for which there is no pool , the rXg may also be configured as a DHCP relay server. This feature enables a DHCP proxy server on the rXg that forwards DHCP requests originating from the associated Ethernet interface or VLAN to an external DHCP server.
Pools
An entry in the DHCP Pools scaffold configures a pool of IP addresses that are to be offered to end-user devices requesting an IP address.
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 start IP and end IP fields define the range of addresses to be offered by this pool. The pool of offered addresses must fall within the range of an IP network configured on an interface and must not include the address(es) consumed by the rXg or the broadcast address. For example, if the 192.168.5.1/24 IP network is configured on the LAN, the maximum allowable range is from the start IP of 192.168.5.2 to the end IP of 192.168.5.254.
It is critically important to be very precise when entering these values to prevent IP address conflicts. Some of the many things to keep in mind include:
- Devices with statically assigned IP addresses must not use addresses within the DHCP pool range.
- IP address reservations (specified in the fixed hosts scaffold) must not be in the pool.
- The pool ranges must be large enough to accommodate the end-user population.
The Reserved options let you specify addresses you wish to reserve either at the begining of each subnet in the pool via the First field or at the end of the subnet via the Last field. For example a network address consisting of 32 /24 subnets (x.x.0.1/24 - x.x.31.1/24 (32)) setting the First field to 4 would reserve x.x.0.2 - x.x.0.5 in the first subnet and .2 - .5 in each subsequent subnet. Setting the Last field to 4 would reserve x.x.0.251 - x.x.0.254 in the first subnet and 251 - 254 in each subsequent subnet. The Router field can change the gateway IP in each subnet. Incremented from the network address, where 1 is the first usable IP address (e.g. x.x.x.1/24). Decremented from the last usable address, where -1 means the last host address (e.g. x.x.x.254/24).
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 option group and class fields link this DHCP pool with options and configuration rules. For example, the WINS server DHCP option can be transmitted to only those end-users running Window through the use of the option group and class fields.
Fixed Hosts
An entry in the Fixed Hosts scaffold reserves an IP address for a particular device. When a device with the MAC address specified in this record requests network configuration via DHCP, the specified IP address is offered. This mechanism is often used as an alternative to manually assigning static IP addresses to devices.
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 IP field contains the IP address to be reserved for this device. It is critically important that the reserved IP be outside of any pools specified in the pools scaffold.
The MAC field contains the MAC address of the device that this reservation is being held for.
The hostname field is an optional parameter that, if specified, will cause the DHCP server to deliver a client identifier to the device via a DHCP option.
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 option group links this reservation with a set of DHCP options that control additional information that may be delivered to the device beyond IP address, hostname, subnet mask and gateway. For example, an option group may be used to specify alternative DNS servers for the device specified in this reservation.
Option Groups
An entry in the option groups scaffold links one or more options to devices that are offered addresses from a pool or set of fixed hosts. When an option is linked, the specified payload will be delivered as part of the DHCP response offered to a requesting device. The use of option groups to link options to pools and fixed hosts maximizes the flexible reuse of configuration options.
The global check box links the associated options with all DHCP responses. Only a single option group can have the global field checked. Furthermore, the global checkbox should be used in exclusion to linking any specific pools and fixed hosts and vice versa.
The authoritative check box indicates whether or not the DHCP server should be authoritative for the network(s) its attached to. An authoritative DHCP server will assume that the configuration information about a given network segment is known to be correct and authoritative, and thus will send DHCPNAK messages to misconfigured clients. Operators setting up DHCP servers for their networks should usually have this checked to indicate that the DHCP server should send DHCPNAK messages to misconfigured clients. If this is not done, clients will be unable to get a correct IP address after changing subnets until their old lease has expired, which could take quite a long time. For certain cluster deployment configurations it is necessary to put the server in non authoritative mode. For example, when two or more cluster nodes are performing the role of the DHCP server on the same network. This is so that the nodes do not NAK each others lease assignments.
The BOOTP check box allows or denies address assignment from the related pool(s) for BOOTP clients.
The options field specifies the members of the options scaffold that will be linked to the targets specified in this option groups record.
The pools and fixed hosts fields specify targets for receiving the DHCP configuration options specified by the options fields.
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.
Options
An entry in the options scaffold establishes a key-value pair that can be appended to any DHCP response via an option group.
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 standard option field specifies the DHCP option that is to be defined by this record. The purpose of the vast majority of the DHCP options is easily derived by the name. The set of all available standard DHCP options is defined by IETF RFC 2132. The custom option field enables the operator to deploy DHCP options that are not part of IETF RFC 2132.
The name makes the purpose of the option self evident in many cases. Here are some common required use cases:
routersWhen the rXg integrated DHCP server is responding to requests originating from a network that is L2 connected to the rXg, the DHCP server automatically populates the response with a next hop router specified as the rXg. However, if the rXg integrated DHCP server is responding to requests on a network that is L3 connected behind a router, the routers option must be specified. In general, it is not possible to automatically determine the IP address of the next hop router that faces the clients being served DHCP, hence the requirement for manual specification.tftp-server-nameCertain forms of customer premises equipment require BOOTP or TFTP provisioning (e.g., DOCSIS cable modems or WiMAX subscriber terminals). To accommodate this, the rXg incorporates a TFTP server and supports the delivery of DHCP responses with the requisite options. The value of the tftp-server-name option should be the IP address of the rXg that is closest to the end-user.
The value is the value that will be used when the key-value pair is appended to the DHCP request. For example, if max-lease-time
is chosen as the option name for a record, the option value should be set to the maximum number of seconds that a DHCP lease can be used by a end-user device.
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 option group field determines which DHCP responses will contain the key-value option pair configured in this record.
The following DHCP client options are currently supported:
Code | Option | Name | Description |
---|---|---|---|
1 | subnet-mask | Subnet Mask | Subnet Mask Value |
2 | time-offset | Time Offset | Time Offset in Seconds from UTC (note: deprecated by 100 and 101) |
3 | routers | Router | N/4 Router addresses |
4 | time-servers | Time Server | N/4 Timeserver addresses |
5 | ien116-name-servers | Name Server | N/4 IEN-116 Server addresses |
6 | domain-name-servers | Domain Server | N/4 DNS Server addresses |
7 | log-servers | Log Server | N/4 Logging Server addresses |
8 | cookie-servers | Quotes Server | N/4 Quotes Server addresses |
9 | lpr-servers | LPR Server | N/4 Printer Server addresses |
10 | impress-servers | Impress Server | N/4 Impress Server addresses |
11 | resource-location-servers | RLP Server | N/4 RLP Server addresses |
12 | host-name | Hostname | Hostname string |
13 | boot-size | Boot File Size | Size of boot file in 512 byte chunks |
14 | merit-dump | Merit Dump File | Client to dump and name the file to dump it to |
15 | domain-name | Domain Name | The DNS domain name of the client |
16 | swap-server | Swap Server | Swap Server address |
17 | root-path | Root Path | Path name for root disk |
19 | ip-forwarding | Forward On/Off | Enable/Disable IP Forwarding |
20 | non-local-source-routing | SrcRte On/Off | Enable/Disable Source Routing |
21 | policy-filter | Policy Filter | Routing Policy Filters |
22 | max-dgram-reassembly | Max DG Assembly | Max Datagram Reassembly Size |
23 | default-ip-ttl | Default IP TTL | Default IP Time to Live |
24 | path-mtu-aging-timeout | MTU Timeout | Path MTU Aging Timeout |
25 | path-mtu-plateau-table | MTU Plateau | Path MTU Plateau Table |
26 | interface-mtu | MTU Interface | Interface MTU Size |
27 | all-subnets-local | MTU Subnet | All Subnets are Local |
28 | broadcast-address | Broadcast Address | Broadcast Address |
29 | perform-mask-discovery | Mask Discovery | Perform Mask Discovery |
30 | mask-supplier | Mask Supplier | Provide Mask to Others |
31 | router-discovery | Router Discovery | Perform Router Discovery |
32 | router-solicitation-address | Router Request | Router Solicitation Address |
33 | static-routes | Static Route | Static Routing Table |
34 | trailer-encapsulation | Trailers | Trailer Encapsulation |
35 | arp-cache-timeout | ARP Timeout | ARP Cache Timeout |
36 | ieee802-3-encapsulation | Ethernet | Ethernet Encapsulation |
37 | default-tcp-ttl | Default TCP TTL | Default TCP Time to Live |
38 | tcp-keepalive-interval | Keepalive Time | TCP Keepalive Interval |
39 | tcp-keepalive-garbage | Keepalive Data | TCP Keepalive Garbage |
40 | nis-domain | NIS Domain | NIS Domain Name |
41 | nis-servers | NIS Servers | NIS Server Addresses |
42 | ntp-servers | NTP Servers | NTP Server Addresses |
44 | netbios-name-servers | NETBIOS Name Srv | NETBIOS Name Servers |
45 | netbios-dd-server | NETBIOS Dist Srv | NETBIOS Datagram Distribution |
46 | netbios-node-type | NETBIOS Node Type | NETBIOS Node Type |
47 | netbios-scope | NETBIOS Scope | NETBIOS Scope |
48 | font-servers | X Window Font | X Window Font Server |
49 | x-display-manager | X Window Manager | X Window Display Manager |
54 | dhcp-server-identifier | DHCP Server Id | DHCP Server Identification |
61 | dhcp-client-identifier | Client Id | Client Identifier |
64 | nisplus-domain | NIS-Domain-Name | NIS+ v3 Client Domain Name |
65 | nisplus-servers | NIS-Server-Addr | NIS+ v3 Server Addresses |
66 | tftp-server-name | Server-Name | TFTP Server Name |
67 | bootfile-name | Bootfile-Name | Boot File Name |
68 | mobile-ip-home-agent | Home-Agent-Addrs | Home Agent Addresses |
69 | smtp-server | SMTP-Server | Simple Mail Server Addresses |
70 | pop-server | POP3-Server | Post Office Server Addresses |
71 | nntp-server | NNTP-Server | Network News Server Addresses |
72 | www-server | WWW-Server | WWW Server Addresses |
73 | finger-server | Finger-Server | Finger Server Addresses |
74 | irc-server | IRC-Server | Chat Server Addresses |
75 | streettalk-server | StreetTalk-Server | StreetTalk Server Addresses |
114 | captive-portal-api | Captive Portal API | Captive Portal API URL |
The following DHCP server options are currently supported:
Option | Description |
---|---|
abandon-lease-time | Maximum amount of time (in seconds) that an abandoned lease remains unavailable for assignment to a client |
adaptive-lease-time-threshold | Specify the % of active leases before the server hands out only short min_lease_time leases |
always-broadcast | Always broadcast responses to clients, regardless of the broadcast bit in the request header |
always-reply-rfc1048 | Always respond with RFC1048-style responses |
default-lease-time | length in seconds that will be assigned to a lease if the client does not ask for a specific expiration time |
dynamic-bootp-lease-length | length in seconds of leases dynamically assigned to BOOTP clients |
filename | Name of the initial boot file which is to be loaded by a client |
get-lease-hostnames | Perform reverse lookup of IP to determine hostname |
infinite-is-reserved | |
one-lease-per-client | Automatically free any other leases the client holds when responding to a request |
ping-check | Ping the IP to ensure it is free before assigning to a client |
ping-timeout | Timeout in seconds to wait for the ping-check to complete |
server-name | Inform the client of the name of the server from which it is booting |
site-option-space | Determine from what option space site-local options will be taken |
stash-agent-options | Record the relay agent information options sent during the initial request message and behave as if those options are included in all subsequent renewal requests |
update-conflict-detection | |
max-lease-time | Maximum length in seconds that will be assigned to a lease |
min-lease-time | Minimum length in seconds that will be assigned to a lease |
min-secs | Minimum number of seconds since a client began trying to acquire a new lease before the DHCP server will respond to its request |
next-server | Address of the server from which the initial boot file is to be loaded |
use-host-decl-names | Supply the scope's host declaration name to the client as its hostname |
Custom DHCP Options
The vast majority of client devices require only basic DHCP in order to achieve network connectivity. Some operators may choose to use standard DHCP options that are defined in IETF RFC 2132 to deliver specific additional configuration. Standard DHCP options may be configured via the DHCP Options scaffold. Between basic DHCP and standard options almost all client devices will get everything they need. Infrastructure devices are a different story.
In some cases certain kinds of devices may require configuration to be delivered via non-standard DHCP options. This usually applies to thin, headless infrastructure devices that depend on a central controller or server such as VoIP handsets, VoD set top boxes, wireless access points, etc. Specialized infrastructure devices. Custom DHCP Options are usually used to deliver bootstrap configuration information such as the IP address and filestore location of initial bootstrap configuration.
The Custom DHCP Options scaffold enables operators to configure the rXg to deliver DHCP options that are not defined byIETF RFC 2132. Each record in the Custom DHCP Option scaffold adds an option to the custom option drop down list in the DHCP Options scaffold. The payload ( value ) to be delivered to the device is configured in the DHCP Options scaffold.
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 type , array and code fields enable the operator to define the headers in the DHCP option that is to being defined. When the array checkbox is enabled, the option will be defined as an array of the type designated. The values of the corresponding DHCP Options should be entered in comma separated format. DHCP vendor-specific option 43 as well as DHCP site-specific option codes between 128 to 254 may be configured to be delivered by the rXg. The exception to this is option 121, classless-static-routes. Static routes may be provided to clients by creating a custom DHCP option and specifying the type as an array of unsigned integer 8, and a code of 121. The value of the corresponding DHCP Option record may be 24,192,168,99,10,10,10,1, 24,172,16,32,10,10,10,2. This would provide a route to 192.168.99.0/24 via 10.10.10.1 and a route to 172.16.32.0/24 via 10.10.10.2. Refer to IETF RFC 3442 for more information.
If the operator desires to deliver payloads via vendor-specific DHCP option 43 then the type should be set to vendor-specific. In this case the code field should be configured to be the DHCP option sub-code that is desired. The settings of the type to vendor-specific implicitly defines the format of the payload to be hex. The payload that is configured by the value field in associated the DHCP Option will be automatically converted to hex from ASCII before being encoded into the option packet.
If the operator sets the type to anything other than vendor-specific then the code represents the site-specific DHCP option that must be between 128 and 254. This limitation is due to the fact that IETF RFC 2132 has already defined DHCP option codes from 0 to 127. The exception to this is the classless-static-routes option, code 121.
The payload of the Custom DHCP Option is defined in the option field of the DHCP Options scaffold and must fall within the range of acceptable possibilities for the given type.
Classes
An entry in the classes scaffold links one or more match rules to devices that are offered addresses from pools. When a match rule is linked, the specifications in the match rule are used to determine membership of the class.
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.
Classes are used to differentiate groups of clients based on matching a substring transmitted as part of the DHCP request or the MAC address of the requesting device. If two pools are created within the network address range associated with a single interface (e.g., 192.168.5.100-150 and 192.168.5.151-200), classes can then be used to populate devices into one of the two ranges based on the request. For example, all requesting devices presenting a dhcp-client-identifier
with a well known predefined prefix can be put into the first pool while all others into the second pool. This alleviates the need to collect and enter the MAC addresses of all devices in a group as fixed hosts in order to place them into a pool.
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 pools fields specifies the pool to place devices into that meet the criteria of the match rules specified by this class.
The match rules field links this class with the match rules that will determine membership.
Match Rules
An entry in the match rules scaffold creates a criteria for selecting DHCP requests to be a member of a class.
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 negate field configure the way the match rule specified by this record behaves. If negate is checked, a DHCP request is considered to be part of a class if it does not meet criteria specified by this match rule.
The logic field controls the way multiple match rules belonging to the same class behave. A setting of and
requires that all criteria be met. Conversely, a setting of or
allows a request to become part of a class if only one of the match rule criteria is met.
The option substring , substring offset and substring length fields control the matching criteria specified in the option value field. If option substring is unchecked, the data in the option value field must exactly match the payload of the DHCP option in the request in order for the request to be considered a match by this match rule. Inversely, if option substring is checked, the substring offset and substring length fields can be used to make a request considered a match if only a portion of the data in option value matches what is presented in the DHCP request. The values that are matched in the option substring are inclusive of the specified boundaries.
The option name and option value are the criteria that determine whether or not a request is a match for this rule. If a DHCP request contains a DHCP option name-value pair matching the data entered into option name and option value , then the DHCP request is considered a match for this rule.
For example, let us consider the case where the RGN distribution infrastructure is DOCSIS cable and composed of Motorola SURFboard cable modems with MAC prefix 00:0A:28, In order to simplify administration, the operator wishes to give all of the cable modems addresses in the 192.168.10.0/24 block and serve 172.16.16.0/24 to the end-users. To accomplish this, the operator would need to configure both DHCP pools and then associate the 172.16.16.0/24 pool with a class that has a match rule configured with:
- option substring - checked
- substring offset - 1
- substring length - 3
- option name - hardware
- option value - 000A28 At first glance, this would seem to be incorrect because we want to match the zeroth through the second byte of the MAC address inclusive. However, the hardware field has the Ethernet prepended onto the MAC address as the zeroth byte. Therefore the actual MAC address is the first to the seventh of the _hardware_field.
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 class field specifies the class for which this matching rule should be used to determine membership.
Relay Servers
An entry in the Relay Servers scaffold enables the DHCP relay feature for the specified interface. DHCP relay allows an rXg to proxy DHCP requests to an upstream DHCP server rather than managing a DHCP pool locally. DHCP relay cannot be used in conjunction with the DHCP server (pools and fixed hosts).
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 server IP field configures the IP address of the upstream DHCP server that will respond to the proxy DHCP requests.
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 interfaces and VLANs fields specify the local physical and logical interfaces to proxy DHCP requests to the server specified by server IP.
DNS
The DNS view contains the scaffolds to configure the rXg core services related to the domain name system.
The rXg integrates a dynamic DNS client that supports all of the major third party dynamic DNS services. Dynamic DNS is an essential part of deploying an rXg in an environment where the uplink address is dynamically assigned and may change.
Many of the rXg services (most notably, the forced browser redirect), require DNS resolution of a domain name to the IP address of the WAN uplink. If the IP address of the WAN uplink is configured via DHCP, it is critically important to reconfigure the DNS whenever the assigned IP address changes. The simplest way to accomplish this is to use the rXg dynamic DNS client.
The rXg also incorporates a fully featured DNS server. The operator can configure the rXg to be a primary, secondary or tertiary domain name server for any domain. Before using the DNS server features of the rXg, it is highly recommended that the administrative staff be familiar with the deployment and operation of the domain name system. Incorrect configuration may render the rXg inoperable. An excellent reference on the domain name system is DNS and BIND (ISBN 0596100574) by Cricket Lui and Paul Albitz.
To configure the rXg as a primary domain name server, the DNS glue records for the domain name must contain the IP address of an rXg uplink. To configure the rXg as a secondary name server, create a DNS zone specifying the primary name server in the master hostname field.
When using the rXg as a primary domain name server, proper DNS glue records must be in place. Most DNS registrars have a web application that enables glue record changes. Updates to glue records sometimes take days to propagate so it important to use a manually assigned static IP address for the rXg uplink.
With the DNS glue records in place, a new entry must be added to the DNS zone scaffold. Set the master hostname to the host name of the rXg and the hostmaster email to something appropriate. At a minimum, two entries must be added to the DNS records scaffold (the nameserver and address records for the rXg itself). Additional resource records may be added so that the rXg provides resolution of desired hostnames.
Dynamic DNS Clients
An entry in the Dynamic DNS scaffold enables the rXg to update third-party dynamic DNS services with the latest WAN IP address configuration. In most cases, a DNS record must be created on the third party dynamic DNS service before updates can be made by the rXg.
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 protocol field determines the communication protocol that will be used to perform dynamic DNS updates. Most of the popular dynamic DNS services have developed their own proprietary protocols. In most cases, the protocol is synonymous with the service, making the choice obvious.
The login and password fields are the authentication credentials that are supplied to the dynamic DNS service when sending updates. These credentials must match those of the account at the third party service in order for updates to be authenticated and accepted.
The hosts field is a comma-delimited list specifying the DNS name(s) that are to be updated. Typically this will be the same DNS name that is specified in the domain name field of the device options scaffold.
The static and wildcard checkboxes modify the payload of the update message sent to the dynamic DNS service. Some services permit automated update of statically configured IP addresses. Usually there is a stipulation that the update frequency must be much lower than that of a dynamic IP. In addition, some services permit the use of wildcard DNS names so that a single entry can cover several hosts. If either kind of record is established on the third party dynamic DNS service, the appropriate checkbox must be set.
The protocol server field is an optional parameter that can be used to specify an alternate destination for dynamic DNS update messages. Since most dynamic DNS services use their own proprietary protocol, selecting a protocol usually determines the destination for the messages. This field enables the operator to override the default destination.
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 IP address sent to the dynamic DNS service in an update message is the uplink IP address of the default rXg route. In single uplink scenarios, this is the network address that is statically associated with the uplink or the dynamic address acquired by the uplink via DHCP. In multiple uplink scenarios, the choice of the default route is controlled by the priority setting of the uplink.
DNS Zones
An entry in the DNS zones scaffold defines a new domain that the rXg integrated DNS server will respond to.
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 domain name field configures the domain that this record will enable responses to.
The master hostname must be set to the fully qualified domain name of the primary master nameserver for this domain. If the rXg is to be the primary master nameserver for the domain, an address record must be configured in the DNS records scaffold.
The hostmaster email field specifies the administrative email address that is reported by the DNS server.
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.
DNS Records
An entry in the DNS records scaffold creates a new record in a zone specified in the DNS zones scaffold.
The host is the host name for this record. The host name is the parameter that is matched when a DNS query is made.
The type field determines the DNS resource record type. The list of dns record types and their function is defined by a series of RFCs published by the IETF.
The dynamic data and data fields define the payload for the DNS resource record. The use of dynamic data and data are mutually exclusive. If a dynamic data field is chosen from the drop down, the response to a query matching the host specified in this record will be the IP address of the uplink specified by the drop down. If data is populated and no dynamic data field is specified, then the response will contain the static payload configured in the data field.
The zone field specifies the DNS zone that this record will be attached to. If "DNS Override" is selected, the rXg will resolve this specific record to the data listed, but all other requests for the same domain will be forwarded on for normal DNS lookup via upstream providers. This avoids having to maintain all records for a domain when attempting to override a single A record.
Domains may be "black-holed" by creating two CNAME DNS Override records, one for domain.com and one for *.domain.com, and setting the data field for both records to "." (no quotes).
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 complete reference of DNS resource records is found in BIND 9 DNS Administration Reference Book (ISBN 0979034213) by Jeremy Reed.
DNS Server
Entries in the DNS Server scaffold define configuration profiles for the rXg integrated DNS server.
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 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.
A properly configured DNS server takes part in a hierarchy of servers starting with the operator of the next hop network all the way to the root DNS servers. By default, the rXg is properly configured to forward requests to the next hop DNS servers. Clearing the request forwarding check box will force the rXg DNS server to make requests directly to the root. Avoid this configuration when possible.
The request forwarding order drop down menu determines the which DNS servers the rXg will query as the next hop. Dynamic servers are those that have been provided via WAN DHCP configuration. Static servers are those that have been manually configured by the operator using the DNS Servers scaffold of the WAN view of the rXg console. Choosing the dynamic,static option tells the rXg to query the dynamically assigned servers first and then the statically assigned servers. Choosing the static or dynamic options tells the rXg to limit queries to the selected set of servers. When multiple uplink control is deployed, the set of dynamic DNS servers is limited to those that are presented by the DHCP server of each pipe. Furthermore, the set of statically configured servers must be accessible via all pipes. This drop down has no effect unless request forwarding is enabled.
The originate queries from port 53 check box configures the DNS server so that upstream UDP queries originate from port 53. This setting may be required if a strict firewall is positioned between the rXg and the upstream DNS server(s).
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
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.
Example: Setup CloudFlare Dynamic DNS
Before we begin we must obtain an API Key from CloudFlare. Navigate to their site and login with your credentials. Click on the person icon in the upper right-hand corner.
Click on "My Profile".
Click on "API Tokens".
Click "View" on the "Global API key".
Enter your CloudFlare password when prompted.
Copy your API Key.
In the rXg navigate to Services::DNS and create a new Dynamic DNS Client.
Give the record a Name. Change the Protocol field to CloudFlare. Enter your email address into the Login field. Enter your API key into the Password field. The Host field is the FQDN to be updated in CloudFlare, and the Zone field is the root domain of the FQDN. Click Create.
When setup the scaffold will update when there is a change.
VPN
The VPN view presents the scaffolds associated with configuring the IPsec and OpenVPN services integrated into the rXg.
OpenVPN Servers
Entries in the OpenVPN Servers scaffold define configuration profiles for the rXg integrated SSL(TLS) VPN.
OpenVPN is an industry standard, open-source software application that the rXg leverages to implement virtual private network (VPN) techniques to create secure point-to-point connections in a routed configuration. It uses a custom security protocol that utilizes SSL/TLS for key exchange. It is capable of traversing network address translators (NATs) and firewalls. The OpenVPN functionality allows peers to authenticate each other using certificates and/or username/password. When used in a multiclient-server configuration, it allows the server to release an authentication certificate for every client, using signatures and certificate authority. It uses the OpenSSL encryption library extensively, as well as the TLS protocol, and contains many security and control features.
https://community.openvpn.net/openvpn/wiki
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.
Each server represents a virtual network interface on a subnet specified by a related Network Address. A separate VPN instance exists for each configured server. A Network Address that is assigned to an OpenVPN interface cannot be configured on a traditional ethernet Interface or VLAN. All servers/networks operate in OpenVPN's TUN (tunnel) mode, which transports only layer 3 IP packets.
If the default gateway field is checked the client will use the VPN interface's IP as its default gateway and DNS server, and route everything over the VPN. An OpenVPN server's Network Address behaves similarly to any other routed subnet behind an ethernet interface or VLAN, in that IP clients behind it are subject to Policy enforcement. For example, creating an IP Group and Landing Portal Policy without a subnet filter for the VPN network would permit the client to access all networks. Conversley, a portal-enabled Policy could be deployed for the VPN client's network. If gateway redirect is not enabled on the server, then it will push routes for all other local networks to a VPN client, which allows it to route through the normal Internet whilst also having knowledge of networks behind the VPN. Note that like any other traditionally-attached subnet, or when the VPN is the default gateway, the routes pushed to the client do not necessarilly ensure firewall access to all networks. In general, an OpenVPN client can also manipulate its routing table independently on a per-client basis.
Authentication from a client may be multi or single-factor via certificates ( require certificate ) and/or username/password ( require login ). If certificates are required, clients must have a unique certificate installed to authenticate. The certificate must be signed by the same CA as the OpenVPN Server's certificate. If multiple devices need to use the same client certificate, the allow duplicate certificates field must be checked, otherwise only one connection per certificate Common Name is permitted. Requiring a unique certificate per client is more secure, but requires each client to have a unique configuration.
If client-to-client behavior is enabled, then clients on the same virtual network can route to each other as if the firewall was disabled. This does not include L2 traffic. Otherwise, if this behavior is disabled, all traffic is forced to route through the rXg and is thus filtered according to Policy enforcement. This should only be enabled when_everyone_ connecting to the same OpenVPN Server should be allowed to communicate.
Configuring the Admin Roles or Account Groups fields permit corresponding Admins and/or Accounts access to the VPN via login. If client certificates are required, the login is only half the authentication process. If client login is not required then these selections are ignored. It is recommended that operators (Admins) and end-users (Accounts) connect to separate OpenVPN Servers. In the case where an OpenVPN Server has Admins and Accounts allowed, an Admin having the same login as an Account always takes precedence for login and instrumentation purposes.
The port and protocol fields define how a client initially connects to the VPN server. A TCP and UDP server may be configured to run on the same port. There are advantages and disadvantages to either protocol (OpenVPN tcp vs udp).
An OpenVPN Server must have a Certificate configured. This identifies the server's certificate and private key in additon to the Certificate Authority (CA) that establishes the PKI used to trust clients. The selected Certificate must be associated with and created from a local Certificate Authority. The certificate must be marked for server usage, meaning it was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules. This can be done when creating the Certificate Signing Request (CSR). This is an important security precaution to protect against a man-in-the-middle attack where an authorized client attempts to connect to another client by impersonating the server.
The cipher and digest options affect the strength of the underlying encryption, where a longer key length increases security and reduces throughput performance. Data compression is enabled by default and is very efficient when LZ4 is employed, which reduces the bandwidth requirements of the VPN at the expense of additional overhead on the client and server.
The TLS-auth option adds an additional layer of HMAC authentication on top of TLS to mitigate DoS and other attacks againist the TLS layer. This is accomplished by including a unique key that resides on top of TLS. The key is generated behind the scenes when an OpenVPN Server is created, and included in the client config output. If a client is configured manually and this is enabled, then the operator must obtain the key from the record via scaffold show action.
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
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.
Clicking the Download Config link will generate an OpenVPN config (.ovpn) file containing the necessary client connection parameters based on the server's configuration, including the Server certificate. Currently, if a client certificate is required, it must be generated manually via the local CA and installed in the client along with the config file.
IPsec VPN
IPsec is an industry standard mechanism that enables secure communication between two nodes or networks that are connected by a potentially insecure IP transit. The rXg supports bidirectional site-to-site IPsec VPNs between rXgs and between rXgs and other kinds of routers. In addition, the rXg may be configured to be a concatenator for host-to-site VPNs originating from nearly any operating system.
Site-to-site VPNs are typically used to enable secure bidirectional communication between two private IP blocks that are behind different routers that are located in geospatially distinct locations. For example, if a WISP has three distinct fixed wireless broadband coverage areas, all three could be linked together via site-to-site VPNs. This could be used as part of a revenue generation strategy such as allowing business customers to access their systems from home for an additional fee.
Site-to-site VPNs are very useful in geospatially diverse deployments that are connected via a central cluster controller. Establishing site-to-site VPNs between the rXgs and the cluster controller enables the operator to easily access all nodes at any part of the network. It is important to keep in mind that the private LAN addresses blocks behind the various rXgs be kept distinct as having the same private LAN block behind two rXgs would cause routing confusion.
Host-to-site VPNs are often used by operators for remote administration. An operator that is on the WAN side of a rXg may use host-to-site IPsec VPNs to directly access machines that are connected to a private address range. In a typical deployment, LAN equipment is assigned IP addresses from private ranges that cannot be reached from the WAN. An operator who is on the WAN side on the rXg (e.g., away on business) that wishes to have complete and direct access to the LAN equipment private address range would setup a host-to-site IPsec VPN using the rXg as the concatenator.
Host-to-site VPNs are also used as a revenue generation mechanism as they are typically sold as a premium service or as a value-added extra part of business class service. End-users originating traffic from the LAN side of the rXg may create a host-to-site VPN using the rXg as a concatenator to protect their traffic from sniffers present in the distribution network. Of course, end-users may also be sold host-to-site VPNs as a mechanism for remote connectivity to nodes addressed on a private LAN.
The rXg uses an industry standard reference implementation of the IPsec suite. Site-to-site VPNs are easily established between an rXg and nearly any other router that supports IPsec VPNs. In addition, site-to-site and site-to-host VPNs may be established between the rXg and almost any operating system released since 2005. Most operating systems have a built-in IPsec stack that is meant to be configured by a trained and certified specialist. However, VPN client software (e.g., Greenbow for Windows and IPsecuritas for Mac OS X) simplify the process to the extent that anybody with a working knowledge of basic TCP/IP can accomplish the task.
IPsec Tunnels
An entry in the IPsec tunnels scaffold is used to configure a site-to-site IPsec VPN.
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 specification field selects the credential and encryption settings for this IPsec tunnel. It is critically important to ensure that the settings in the chosen IPsec specification matches those of the node at the other end of the site-to-site VPN created by this IPsec tunnel.
The Pre-Shared key and Certificates fields are used to configure the certificates or pre-shared key that will be used for authenticating IPsec tunnels that use this IPsec specification. The operator may choose to use one or more certificates or a pre-shared key but not both. If one or more certificates are chosen, then the node at the other end of the IPsec tunnel must have the matching private key. If a pre-shared key is chosen, then the node at the other end of the IPsec tunnel must have the exact same pre-shared key programmed.
The addresses and static routes checkboxes specify which LAN address blocks will be forwarded to the remote node of this site-to-site VPN.
The remote gateway field specifies the IP address of the node at the other end of this site-to-site IPsec VPN.
The remote networks field specifies the IP address blocks at the other end of this site-to-site VPN that will be routable once the VPN is established.
Conflicts between addresses or static routes and remote networks will cause severe routing problems. In situations where multiple site-to-site VPNs will be deployed, it is critically important to carefully plan the addressing across all current and potential future networks.
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.
IPsec Specifications
An entry in the IPsec specifications scaffold defines an IPsec policy that can be used for bidirectional site-to-site VPN tunnels as well as host-to-site VPN concatenation.
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 a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
The IKE Version field allows the operator to select which IKE(Internet Key Exhange) version to use for the tunnel. IKEv1 and IKEv2 are supported.
The phase 1 and phase 2 groups are used to configure the encryption specifications for the initialization and operational phases of a IPsec tunnel. The chosen encryption , authentication , Diffie-Hellman group , exchange mode and proposal check must exactly match the settings on the node at the other end of the IPsec tunnel.
The encryption field specifies the algorithm that will be used for bulk encryption of the packet data that will transit the VPN connection. The DES option is included for reference only and should be avoided as it is trivially broken given contemporary computing power. The 3DES and AES options are the most compatible and generally accepted to be strong enough for most purposes. AES is preferable as it is the new government standard encryption protocol. Blowfish and CAST are less known protocols but widely believed to be as strong if not stronger than AES but not as well supported.
The authentication field specifies the algorithm that will be used for generating cryptographic hashes to authenticate data passing through the VPN connection. The MD5 option is included for reference only and should be avoided as researchers have discovered methods to break it. The SHA1 option is the most compatible option as it is broadly supported. If possible, the SHA256, SHA384 or SHA512 options as researchers have found a handful of minor vulnerabilities in SHA1 to date.
The Diffie-Hellman group and PFS group fields configure the strength of the encryption keys that will be used to protect the session keys used by the encryption algorithm. The stronger the key, the less likely that it will be broken. However, the stronger the key, the more CPU utilization and entropy it will consume and less compatible it will be. The Group 1 / 768 bit key length option should be avoided unless the other end of the VPN cannot support any other option. The Group 2 / 1024 bit key length is the absolute minimum key strength that should be used for a production environment. The longer key lengths are recommended if the other end of the VPN connection supports it.
The lifetime field configures the length of time in seconds of the security association. A shorter lifetime causes the system to rotate keys more often (potentially increasing security). As a result, shorter lifetimes will increase CPU utilization and entropy consumption.
The nonce field configures the size of the "number used once" for IPsec initialization. A longer nonce helps prevent replay attacks, but trades off CPU utilization and entropy consumption. A longer nonce is also less compatible with other IPsec implementations.
IPsec Server
Entries in the IPsec Server scaffold define configuration profiles for the rXg integrated IPsec server.
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 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 Pre-Shared key and Certificates fields are used to configure the certificates or pre-shared key that will be used for authenticating IPsec tunnels that use this IPsec specification. The operator may choose to use one or more certificates or a pre-shared key but not both. If one or more certificates are chosen, then the node at the other end of the IPsec tunnel must have the matching private key. If a pre-shared key is chosen, then the node at the other end of the IPsec tunnel must have the exact same pre-shared key programmed.
The anonymous specification field selects the credential and encryption settings for anonymous IPsec connections (i.e., where the client's originating IP address is unknown). Pre-shared-key authentication may not be used for anonymous connections. An anonymous IPsec client must authenticate using a certificate. The certificates to be used by the anonymous clients should be configured in the IPsec Specifications scaffold for the selected anonymous specification. It is critically important to ensure that the settings in the chosen anonymous specification match those of the IPsec client.
The certificate field specifies an alternate certificate to configure the IPsec server with.
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
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.
Site-to-site IPsec VPN Configuration
Site-to-site IP-sec VPNs enable devices that are behind VPN concatenators to communicate with each other securely without any configuration changes to the end-user devices. In most cases, site-to-site IPsec VPNs are deployed with privately addressed end-user devices behind the VPN concatenators. Without a site-to-site IPsec VPN, the privately addressed devices would not be able to initiate communication with each other due to the one-way nature of network address translation. Consider the following network diagram:
In this example, we have two rXgs and we desire to create a site-to-site IPsec VPN to enable two way communication for devices that are on private addresses behind the rXgs. We will call the rXg on the left with WAN IP 66.67.68.2 east and the rXg on the right with WAN IP 55.45.35.2 west. The network dashboard of the_east_ rXg is shown below:
The rXg IPsec VPN feature is compatible with a broad spectrum of IPsec implementations. It is not necessary for a site-to-site VPN to be established between two rXgs. We have used two rXgs in this example so that we can best illustrate the appropriate configuration for either end of the site-to-site VPN. The network dashboard of the_west_ rXg is shown below:
Notice that both rXgs have a single private LAN block associated with them. The east rXg has 192.168.6.0/24 behind it and the west rXg has 192.168.7.0/24 behind it. When configuring IPsec VPNs, it is critically important to ensure that the networks behind the various endpoints of the IPsec VPN do not intersect. This is because IPsec depends on a valid L3 (routing layer) configuration in order to operate.
Establishing a site-to-site VPN is simply a matter of creating a single record in the IPsec Tunnel scaffold on both ends of the connection. The remote gateway field must be set to the IP address of the concatenator on the other end of the site-to-site VPN. The remote networks field must contain the CIDR of the block present on the other end of the site-to-site VPN.
Following our example, the IPsec tunnel record on east(which has WAN IP address 66.67.68.2, LAN address 192.168.6.1 / 24) must have the following settings:
- remote gateway - 55.45.35.2
- remote networks - 192.168.7.0/24
Below is a screenshot of the configuration that is present on east:
Similarly, west (which has WAN IP address 55.45.35.2, LAN address 192.168.7.1 / 24) must have the following settings in the IPsec tunnel record:
- remote gateway - 66.68.67.2
- remote networks - 192.168.6.0/24
Below is a screenshot on configuration that is present on west:
Notice that the IPsec Tunnel records depend on the existence of an IPsec Specification record in order to configure the encryption protocol and keys for the tunnel. In the configuration screenshots shown above, we seen that the specification is referenced as PSK for S2S. A screen shot of the configuration for_PSK for S2S_ that is present on both east and _west_is shown below:
Since we are configuring a site-to-site VPN, we are assuming that both ends of the connection are controlled by trusted parties. Thus we will use a pre-shared key to secure the connection. To accomplish this, we will create a new record in the IPsec Specifications scaffold on both the east and west rXgs. To get a site-to-site IPsec VPN up and running, the individual choices for the encryption protocol and credentials are not as important as the simple fact that they must be exactly the same on both machines. Using a strong pre-shared key is obviously a prerequisite to maintaining the confidentiality and integrity of the VPN.
Several templates are provided as examples for strong, medium and minimum security configurations. The minimum security configuration is the least secure against brute force attacks but is the most compatible. The template for the most secure setting will only function with KAME derived IPsec stacks such as the ones present in OpenBSD and FreeBSD. For more information on the precise meaning behind each of the settings, we recommend reading information that may acquired via a search on IPsec. When configuring a site-to-site VPN, keep in mind that even the slightest difference in a single setting will prevent the site-to-site IPsec VPN from initializing.
For your reference, the complete IPsec configuration for both_east_ and west is shown below:
Once we have this configuration in place on both east and_west_, devices on the 192.168.6.0 / 24 private network behind_east_ may directly contact devices on the 192.168.7.0 / 24 private network behind west and vice versa. Note that absolutely no configuration changes needs to be made on the end-user devices whatsoever. All of the encryption, decryption and routing between the private networks is handled by the IPsec VPN endpoints, which in this case are the east and west rXgs.
For example, let us assume there is a Windows XP laptop behind_east_. The XP machine will acquire a DHCP address in the 192.168.6.0 / 24 CIDR. Similarly, let us assume there is a Windows 2003 server behind west that is on the 192.168.7.0 / 24 CIDR. Given the site-to-site VPN configuration that we have created on the rXgs, the XP laptop will be able to directly communicate with the Win2k3 server without any configuration changes to the clients.
The screenshot below shows the desktop of the Windows XP laptop that is behind east. It has acquired address 198.168.6.100 / 24 from the east rXg. Notice that it can ping the private address 192.168.7.100 directly. The 192.168.7.100 address is configured on the Windows 2003 Server that is behind the _west_rXg.
No configuration changes were made to the Windows XP laptop whatsoever. The Windows XP laptop has no knowledge that the 192.168.7.100 is behind the west rXg. The 192.168.7.100 could be on the other side of the world and the XP laptop would not know any better. Furthermore, the XP laptop does not do any encryption or decryption of traffic. It merely sends traffic to the east rXg which does all of the work in encrypting and forwarding the traffic to the west router for delivery to 192.168.7.100.
The screenshot below shows the desktop of the Windows 2003 Server that is behind east. It has an address of 198.168.7.100 / 24 which is behind the west rXg. Notice that it can ping the private address 192.168.6.100 directly. As depicted in the previous screenshot, the 192.168.6.100 address belongs to the Windows XP laptop behind the east rXg.
The Windows 2003 Server has no knowledge about the site-to-site IPsec VPN. The Win2k3 server simply forwards packets to the_west_ rXg which does all of the work involved in the encryption and routing of packets to 192.168.6.100 via east.
The site-to-site IPsec VPN enables routing between private networks to occur over the public Internet that is otherwise not possible. Once established, any network application may be used. In the screenshots below, the Windows XP client on 192.168.6.100 behind east_is shown initiating and utilization a remote desktop connection to manage the Windows 2003 Server on 192.168.7.100 behind _west.
Site-to-site IPsec VPNs enable RGN operators to have secure remote access to all of their various networks. Any devices that is on a private network behind an rXg may be accessed as if it is a local device at the other end of the site-to-site VPN without any configuration changes to the devices themselves. The possibilities of what site-to-site IPsec VPNs may be used for is limitless. Many RGN operators deploy site-to-site VPNs for remote access as demonstrated above. Another frequent use of site-to-site VPNs is for monitoring. For example, site-to-site VPNs may be used to enable a central site to have a single network monitoring system (NMS) or element monitoring system (EMS) to monitor multiple remote networks.
Host-to-site IPsec VPN Configuration
Host-to-site VPNs are used with the rXg to securely route data between a specific end-user device and the rXg. Host-to-site VPNs may be initiated to the rXg from the WAN or the LAN. The process and technical steps of creating either a WAN to rXg or LAN to rXg host-to-site VPN are identical. However, the use case and business reasons for using the two topologies are radically different.
If the end-user device is on the WAN-side of the rXg, a host-to-site VPNs is usually deployed for the purpose of remote access to local privately addressed machines similar to a site-to-site VPN. However, a host-to-site VPN obviates the need to deploy and configure a VPN concatenator on the end-user network.
A WAN host-to-site VPN is the appropriate methodology to use with a mobile client used by a network administrator that requires access to privately addressed resources when the mobile client must connect to networks which the administrator does not control. For example, if the mobile client uses a wireless WAN connection (e.g., cellular 3G), it would be more difficult to install a VPN concatenator for site-to-site VPN than it would be to configure the device for host-to-site VPN. The use of host-to-site VPNs is ubiquitous in enterprise networks to the extent that even mobile phones operating systems such as Symbian, Windows Mobile and Apple iPhone OS are capable of initiating host-to-site VPNs.
Host-to-site VPNs originating from the LAN-side of the rXg are typically deployed as a facet of revenue generation for the operator. Popular media has helped educate most end-users to understand that there are many security issues present when computer networks are used. This effect may be exploited by RGN operators for the purpose of generating additional revenue by offering security related premium services.
For example, if the LAN distribution mechanism is wireless, a host-to-site IPsec VPN upgrade may be offered to end-users to provide confidentiality and integrity to the traffic over the wireless portion of the Internet link. Enabling the anonymous IPsec VPN capability and integrating the generation of a client certificate into the rXg captive portal allows operators to enjoy zero operator intervention provisioning of host-to-site VPNs.
Host-to-site IPsec VPNs typically use public key cryptography in order to authenticate the initiating hosts. Each initiating host must have a unique keypair in order to ensure the confidentiality and integrity of the IPsec VPN connection. In addition, the IPsec VPN concatenator must identify itself with a keypair to the initiating client. The rXg uses X.509 certificates and private keys for the purposes of authenticating both ends of a host-to-site IPsec VPN.
The rXg expects that the operator has stored certificates for each of the hosts that will be initiating a host-to-site IPsec VPN in the certificates scaffold on the certificates view. When a host-to-site IPsec VPN connection is initialized, the rXg expects that the initiating client will authenticate by using the matching private key to sign an authentication credential. Similarly, the rXg must be configured with a private key and certificate for authenticating the site. The initiating client is assumed to have a copy of the rXg certificate and the rXg will sign an authentication credential with the matching private key.
The certificates view of the rXg administrative console may also be used to create keypairs that may be used for authenticating host-to-site IPsec VPNs. To accomplish this, use the certificate authorities scaffold to create a new authority that can be used to sign certificate signing requests to fully populate certificates. For more information, please see the documentation on the certificates view.
In order to instantiate a host-to-site IPsec VPN, configuration changes must be executed on both the rXg and the end-user device. However, the same process is used to configure the end-user device and the rXg to enable a host-to-site IPsec VPN concatenator regardless of whether the VPN will be initiated from the WAN or LAN. Let us consider the east rXg that was discussed earlier. The configuration and network diagram for the east rXg is shown below:
The rXg must be configured to allow anonymous connections to enable the host-to-site IPsec VPN capability. To accomplish this, an entry in the IPsec servers scaffold must be created that specifies the site authentication certificate. The IPsec server record must be linked to a IPsec specification record that defines the encryption protocol as well as the client certificates that will be accepted for connection initiation.
The configuration steps of the end-user device needed to setup a host-to-site VPN follow the same pattern regardless of the operating system of the end-user device. At a bare minimum, the following items need to be configured in order for a host-to-site IPsec VPN to be established:
- host certificate
- host private key
- IP address of VPN router
- remote network CIDR
- encryption protocol and associated parameters The precise steps that are needed depend on both the operating system as well as the VPN client software. Many popular operating systems have "bare metal" VPN clients built into them that are suited for operation by IT professionals. However, in almost all cases, user friendly VPN client GUIs are available from both free and commercial sources.
The IPsec capabilities of all recent versions of Microsoft Windows is configured using the Microsoft Management Console. Depending on the specific of Windows, the MMC snap-in will be called something like "IP Security Policy Management" or "Windows Firewall with Advanced Security." Search the web for Microsoft'sstep by step guide to deploying Windows firewall and IPsec policies and review pages 15-17 as well as 89-91 for specific instructions. For those who are less technically inclined, we have that the Greenbow VPN client greatly simplifies the creation of host-to-site IPsec VPNs on Windows.
The MacOS X operating system incorporates numerous open source components into its IPsec VPN stack. This makes the MacOS X IPsec VPN one of the most compatible of the commonly available commercial offerings. However, the command line configuration is needed to setup the IPsec stack for the vast majority of use cases. For this reason, we recommend that users download and install the IPsecuritas freeware GUI to configure host-to-site IPsec VPNs between MacOS X clients and rXgs.
Example OpenVPN Configuration
- Create certificate
- Create Networking
- Configure OpenVPN in rXg
Navigate to System-->Certificates. If there are no Certificate Authorities we will need to create one to self sign our OpenVPN certificate. Click Create New on the Certificate Authorities scaffold.
Name is arbitrary and be set to anything. Days by default will be 825. Common Name does not need to resolve for the purposes of using OpenVPN. Fill out the remaining fields with the appropriate information for your location. Click Create.
Next create a new Certificate.
For the certificate only the name needs to be entered at this step. Verify CA is set to Local CA. Click Create.
Next create a new Certificate Signing Request.
Verify that the Certificate field is set to the correct certificate. Sign mode should be set to Generate CSR and sign with linked local Certificate Authority. Common Name should match the Common Name in the Certificate Authority. Fill out the remaining fields with the appropriate information if applicable. Click Create.
Next we need to create the networking that will be used for devices connecting to the OpenVPN. Navigate to Network-->LAN, and create a new Network Address.
Enter a name. Make sure that Interface is set to -select- for each box. The IP field will be the addresses available to devices connecting via OpenVPN and should be entered in CIDR notaton. Autoincrement and Span should be left set to 1, do not check Create DHCP Pool. Click Create.
Navigate to Services-->VPN and create a new OpenVPN Server.
Enter a name, or use the default. Under Client Configuration Network should be set to the Network Addresses we created earlier. If you want traffic to route through the remote system check the Default gateway option. Require login is checked by default and this prevents access except for Admin Roles we have selected in this example. Server Options will be left at their default values for this example. WAN Targets can be selected to further restrict access if desired. Click Create.
Now the config can be downloaded from the rXg and imported into a VPN client of choice.
Notifications
The notifications view presents the scaffolds associated with configuring templates for email, SMS, webhooks, and event health notices in response to events.
The notification actions scaffold enables clear communication to the RG end-user population, operators and administrators, as well as other systems.
Email is one of several end-user communication methods that are used to create a complete revenue generating network strategy. Email is an important part of the feedback loop when end-users purchase services. Event-based email notifications bring confidence to the end-user by offering a "receipt" when billing events occur. In addition, email can be used for marketing and administrative communication conveyance.
The rXg also uses email as a mechanism to communicate events to administrators. Events may be end-user related such as the service purchase case discussed before, or they may be system generated. Examples of system generated events include, but are not limited to, output from daily, weekly and monthly recurring system maintenance tasks, changes to uplink and monitored node status as well as detection of internal system problems.
The rXg sends emails to administrators and end-users when certain events occur (e.g., account creation, plan selection, etc.). These event-based email notifications draw from templates defined in the custom messages template. The templates may be customized for content, look and feel as well to change the language to match the locale.
custom message templates also be used by the administrator initiated bulk email jobs. For example, the administrator may wish to send some or all end-users an email indicating a maintenance window, a reduced price service special or a paid advertisement from a partner.
The rXg email mechanism also helps operators generate revenue by enabling bulk email marketing. For example, if an operator becomes an affiliate marketing program subscriber, the operator will receive email notifications of special offers. In many cases, affiliate marketing program subscribers are given the opportunity to offer exclusive discount codes to their market base as a purchasing incentive. When an operator receives such a notification, a new email template incorporating affiliate program linkage and incentive information may be formulated and a job created broadcast to the end-user population. The operator is then issued a credit For end-users who take advantage of the opportunity described in the bulk email.
Significant operational cost reduction may also be achieved through the use of the rXg bulk email mechanism. Notification of maintenance windows, end-user surveys, promotions and well-checks may all be accomplished via the bulk email mechanism. Using the bulk email mechanism minimizes the hours utilized by support staff to communicate system and network administration events. In addition, keeping end-users informed often and ahead of time helps reduce support load in maintenance situations.
Below is an example Custom Message that reports to the recipients the amount of revenue generated in the previous 24 hour period:
<p>Good Morning,</p>
<%
rev = ArTransaction.where(['created_at > ?', 24.hours.ago]).sum(:credit)
%>
<p>Your network generated $
<b><tt><%= sprintf("%.2f", rev) %></tt></b>
yesterday. Have a nice day.
</p>
The Ruby script embedded inside the Custom Message above performs a calculation on the ArTransactions to generate a report for the recipients. Ruby scripts may also perform write operations on the database. For example, below is a Custom Message that is configured to be sent to a guest services representative on a daily basis.
<p>Good Morning,</p>
<%
todays_credential = sprintf("%x%d", rand(255), rand(9999))
scg = SharedCredentialGroup.find_by_name('Guests')
scg.credential = todays_credential
scg.save
%>
<p>Today's shared credential for guest access is:</p>
<p><b><tt><%= todays_credential %></tt></b></p>
<p>Thank you.</p>
The Ruby script embedded inside the Custom Message changes the designated Shared Credential Group to a randomly generated value and notifies the associated administators.
Adding Graphs to Custom Messages
Network, System, and Accounting graphs may be added to your custom messages in order to provide enhanced reporting emails to operators and administrators. By selecting associated Graph records in the custom messages's configuration, the system will automatically generate and attach PNG images of those graphs to the email as attachments.
Additionally, graph images may be inserted into the body of an email by calling the insert_attached_graphs method inside the body. The method takes an optional argument specifying the resolution of the image, such as_1000px*600px_ (the default). The resulting images will be stored on the rXg in a publicly accessible directory such that they may be retrieved by email clients.
For example, below is a Custom Message that inserts all associated graphs into the body of the email, separated by a line-break (<br>).
<h2>Weekly Report</h2>
<h3><%= Date.today.strftime("%a, %B %d, %Y") %></h3>
<br>
<%= insert_attached_graphs('1200px*700px') %>
If you wish to exercise greater control over the structure of your HTML email, you may provide a block to the method. The block will yield an array of hashes in the format of { graph_object => image_tag_string }. The array may be iterated over to insert each image tag into your desired HTML structure. For example:
<h2>Weekly Report</h2>
<h3><%= Date.today.strftime("%a, %B %d, %Y") %></h3>
<br>
<table>
<% insert_attached_graphs('600px*500px') do |graph_tags| %>
<% graph_tags.each do |graph, image_tag| %>
<tr> <td align="center" style="font-size:34px"><%= graph.title %></td> </tr>
<tr> <td align="center" style="font-size:14px"><%= graph.subtitle %></td> </tr>
<tr> <td><%= image_tag %></td> </tr>
<% end %>
<% end %>
</table>
Webhooks, and Webhook Targets 
The webhooks and webhook targets scaffolds enable an operator to integrate other systems with the rXg. Webhooks user defined HTTP callbacks which are triggered by specific events. The events are configured in the notification actions scaffold. When the triggered event occurs, a webhook gathers the required data (headers, and body), and sends it to the configured URL.
An entry in the webhook targets scaffold defines a set of 'global' parameters that all webhooks configured for the target will use. These include the Base URL, body formatting, error code response, as well as any global HTTP headers, or query parameters an operator may need to configure. This enables the flexibility to configure multiple unique webhooks, utilizing a common target, and eliminates the need for repeating common elements such as API-keys, or content-types on each configured webhooks
An entry in the webhooks scaffold defines the parameters for a single webhook. A webhook must have an associated webhook target, containing the base URL. The specific endpoint path is defined in the webhook scaffold entry. The path will be appended to the webhooks configured target base URL. An operator can override the base URL by starting the webook path with a /
. The HTTP request method, as well as the body or data is also configured within the webhook scaffold. Any additional HTTP headers, or query parameters that are unique to the configured webhook can be added.
Notification Actions
An entry in the notification actions scaffold defines an event of which the rXg should complete the selected action(s). Events can include database changes, time and/or location based triggers, and more.
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 a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
The event type field selects what kind of events should trigger a configured action. Depending on the selection, additional options may be rendered for operator configuration. For database changes, an operator can select Watch Scaffold
, choose the appropriate modifiers (create, update, and/or delete).
The messages field configures a custom message to be sent when the criteria of the event is met. The message recievers are configured in the custom messages scaffold entry.
The webhooks field defines configured webhooks to be triggerd when the criteria of the event is met.
The health notice field defines whether the system should send a health notice. Choosing default
will result in the default behavior of a configured event. For instance, "Certbot Failure" is configured to send a health notice on failure. If the event does not have a default health notice action, nothing is changed, and no health notice is sent. Choosing Disabled
, will override the configured default health notice the event type, and not send it. For instance, with "Certbot Failure", choosing disabled will disable a health notice from being sent. Choosing Custom
allows the operator to configure or override an existing health notice. For instance, "Watch Scaffold :: Administrators" wouldn't trigger a health notice by default. Choosing custom would allow an operator to configure a health notice for this event type.
Custom Messages
An entry in the custom messages scaffold creates a template that can be used for email notifications and bulk emails originating from the rXg.
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 event drop down associates this template with an event which will trigger an email notification to an end-user. If no event is chosen, the template is assumed to be used in only an email campaign.
The from field defines the address from which emails sent using this template will originate. This email address should lead to an account that is regularly monitored because end-users who receive emails based on this template are likely to reply with questions.
The account and admin roles check boxes enables automatic sending of emails using this custom message for event notification. If the account check box is checked, then the custom message template will be populated with the appropriate data and transmitted to the end-user when the selected event occurs. Similarly, when one or more admin roles check boxes are checked, the custom message template will be populated with the appropriate data and send to the administrators who are linked of the to the checked admin role.
The subject and body fields define the payload of the email template. Place the desired content for the subject and message into the appropriate field. Placeholders for variable substitutions begin and end with the percent sign and must refer to fields from the usage plans or accounts scaffolds. For example, %account.first_name% %account.last_name%
will be substituted for the full name of the end-user being targeted by the email. See the full manual page for more information about the values available for substitution.
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.
Email Campaigns
An entry in the email campaigns scaffold defines a bulk email job. Once the job is complete (i.e., all emails are queued for transmission), the entry in email campaigns is automatically deleted.
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 custom message field selects the template that will be used for this bulk email job. The template payload is defined in the custom messages scaffold.
The account groups field configures the set of end-users who will be sent the email template selected by the custom message via this job. The members of the groups are controlled by the account groups scaffold on the accounts view of the identifies subsystem.
The start at field defines the starting time and date for this job. If the value of the start at field is before the current date and time, the job will be started immediately. If the start at is set to the future, the job will start at the specified future date and time.
A job is automatically deleted after it is finished. The optional frequency field determines if this job is run more than once, and how often. The optional end at field defines when a repeat job is finished. A job with a set frequency and a blank end at field will repeat indefinitely at the configured frequency. A periodic job with a configured end at field is deleted when the time of the next iteration exceeds the end at date/time.
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.
SMS Gateways
The SMS Gateways scaffold enables the creation of an SMS Gateway service which will be utilized for verifying a user's mobile number for the purpose of new account signups and/or password resets.
The name field identifies this SMS Gateway in the system.
The provider field specifies which provider this SMS Gateway relates to. Select a supported provider from the list.
The from field specifies the phone number, shortcode, or Alphanumeric Sender ID (not supported in all countries) to be used when sending SMS messages through this gateway. This value must correspond to a number purchased from or ported to the provider.
The Account SID and Auth Token fields specify the API credentials used to access the provider's REST API, and may be obtained from your dashboard within the provider's website.
The Usage Plans selections determine which usage plans are configured to utilize this SMS Gateway. The usage plan must also specify a validation method which includes SMS in order for messages to be sent via SMS.
The Splash Portals selections determine which splash portals are configured to utilize this SMS Gateway for the purposes of performing password resets. Accounts with a valid mobile phone number may request a password reset token via SMS or Email, depending on the password reset method specified in the splash portal.
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.
For more information, see the SMS Integration manual entry.
Webhook Targets
An entry in the webhook targets scaffold defines a remote endpoint the rXg should send configured webhooks to.
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 a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
The base url field should be configured with the top-level/base URL of the remote API endpoint. This allows for flexibility to have multiple webhooks configured to use the same target.
The persistent connection checkbox configures the rXg to send 'keep-alive' headers and persist the connection state.
The resend on failure checkbox configures the rXg to attempt resending if the initial connection fails.
The error status codes field defines a list of codes that should be considered error responses. The use of wildcard 'x' is available to the operator. Examples include: (400, 401, 4xx, 500, 5xx, 50x).
The body format selector defines the formatting of the body of webhooks configured to use this target. Selecting JSON
automatically addsapplication/json
to the HTTP Header content-type. SelectingProtobuf
requires the operator to define a protobuf schema.
The body encoding selector defines an optional encoding scheme. Options include RAW (no encoding), Base64, and Base64 w/newline every 60 characters.
The webhook properties fields allow the operator to define additional HTTP Headers, or Query Parameters to send globally with all webooks configured to use this target.
Webhooks
An entry in the webhooks scaffold defines the body, target, method, and additional HTTP Headers and/or Query Parameters for a configured webhook.
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 a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
The notification actions field displays what actions this webhook is configured for.
The webhook target dropdown configures the webhook target this webhook will use.
The path field is appended to the base url of the webhook target. This allows multiple webhooks to use the same webhook target, and be configured for unique endpoints.
The body field contains the body of the webhook.
The buffer field configures a time period (in minutes) before sending the webhook. "0" will disable buffering.
The webhook properties selector defines an optional encoding scheme. Options include RAW (no encoding), Base64, and Base64 w/newline every 60 characters.
The webhook properties fields allow the operator to define additional HTTP Headers, or Query Parameters to send only with this individual webhook.
Substitution
Payload fields may contain special keywords surrounded by % signs that will be substituted with relevant values. This enables the operator to deliver values stored in the database as part of the payload.
List of objects available:
Account Create | Usage Plan Purchase | Transaction: success/failure |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
ip_group | login_session | login_session |
login_session | usage_plan | merchant |
usage_plan | account | payment_method |
account | merchant_transaction | |
usage_plan | ||
account |
Credit Card Expiring | Coupon Redemption | Account Charge: success/failure/no response |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
login_session | coupon | login_session |
payment_method | login_session | payment_method |
usage_plan | usage_plan | response |
account | account | usage_plan |
account |
Trigger: Connections | Trigger: Quota | Trigger: DPI |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
login_session | login_session | login_session |
max_connections_trigger | quota_trigger | snort_trigger |
transient_group_membership | transient_group_membership | transient_group_membership |
account | account | account |
Trigger: Time | Trigger: Log Hits | Health Notice: create |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
login_session | login_session | health_notice |
time_trigger | log_hits_trigger | |
transient_group_membership | transient_group_membership | |
account | account |
Health Notice: cured |
---|
cluster_node |
custom_email |
device_option |
health_notice |
List of objects available for all associated record types:
Aged AR Penalty |
---|
cluster_node |
custom_email |
device_option |
aged_ar_penalty |
login_session |
payment_method |
usage_plan |
account |
List of attributes available for each object:
account | usage_plan | merchant |
---|---|---|
id | id | id |
type | account_group_id | name |
login | name | gateway |
crypted_password | description | login |
salt | currency | password |
state | recurring_method | test |
first_name | recurring_day | note |
last_name | variable_recurring_day | created_at |
automatic_login | updated_at | |
usage_plan_id | note | created_by |
usage_minutes | created_at | updated_by |
unlimited_usage_minutes | updated_at | signature |
usage_expiration | created_by | partner |
no_usage_expiration | updated_by | invoice_prefix |
automatic_login | time_plan_id | integration |
note | quota_plan_id | store_payment_methods |
logged_in_at | usage_lifetime_time | live_url |
created_at | absolute_usage_lifetime | pem |
updated_at | unlimited_usage_lifetime | scratch |
created_by | no_usage_lifetime | dup_timeout_seconds |
updated_by | recurring_retry_grace_minutes | |
mb_up | recurring_fail_limit | |
mb_down | prorate_credit | |
pkts_up | permit_unpaid_ar | |
pkts_down | pms_server_id | |
usage_mb_up | lock_devices | |
usage_mb_down | scratch | |
unlimited_usage_mb_up | max_sessions | |
unlimited_usage_mb_down | max_devices | |
company | unlimited_devices | |
address1 | unlimited_sessions | |
address2 | usage_lifetime_time_unit | |
city | max_dedicated_ips | |
region | pms_guest_match_operator | |
zip | recurring_lifetime_time | |
country | recurring_lifetime_time_unit | |
phone | unlimited_recurring_lifetime | |
bill_at | sms_gateway_id | |
lock_version | validation_method | |
charge_attempted_at | validation_grace_minutes | |
lock_devices | max_party_devices | |
relative_usage_lifetime | unlimited_party_devices | |
scratch | upnp_enabled | |
portal_message | automatic_provision | |
max_devices | conference_id | |
unlimited_devices | ips_are_static | |
max_sessions | base_price | |
unlimited_sessions | vtas_are_static | |
max_dedicated_ips | manual_ar | |
account_group_id | ||
email2 | ||
pre_shared_key | ||
phone_validation_code | ||
email_validation_code | ||
phone_validated | ||
email_validated | ||
phone_validation_code_expires_at | ||
email_validation_code_expires_at | ||
max_party_devices | ||
unlimited_party_devices | ||
nt_password | ||
upnp_enabled | ||
automatic_provision | ||
ips_are_static | ||
guid | ||
vtas_are_static | ||
account_id | ||
max_sub_accounts | ||
unlimited_sub_accounts | ||
approved_by | ||
approved_at | ||
pending_admin_approval | ||
wispr_data | ||
hide_from_operator |
payment_method | merchant_transaction | coupon |
---|---|---|
id | id | id |
account_id | account_id | usage_plan_id |
active | payment_method_id | code |
company | merchant_id | credit |
address1 | usage_plan_id | expires_at |
address2 | amount | note |
city | currency | created_by |
state | test | updated_by |
zip | ip | created_at |
country | mac | updated_at |
phone | customer | batch |
note | scratch | |
created_at | merchant_string | max_redemptions |
updated_at | description | unlimited_redemptions |
created_by | success | |
updated_by | response_yaml | |
scratch | created_at | |
customer_id | updated_at | |
card_id | created_by | |
nickname | updated_by | |
encrypted_cc_number | message | |
encrypted_cc_number_iv | authorization | |
encrypted_cc_expiration_month | hostname | |
encrypted_cc_expiration_month_iv | http_user_agent_id | |
encrypted_cc_expiration_year | account_group_id | |
encrypted_cc_expiration_year_iv | subscription_id | |
encrypted_first_name | ||
encrypted_first_name_iv | ||
encrypted_middle_name | ||
encrypted_middle_name_iv | ||
encrypted_last_name | ||
encrypted_last_name_iv | ||
cc_number | ||
cc_expiration_month | ||
cc_expiration_year | ||
first_name | ||
middle_name | ||
last_name |
login_session | ip_group | device_option |
---|---|---|
id | id | id |
account_id | policy_id | name |
radius_realm_id | name | active |
login | priority | device_location |
ip | note | domain_name |
mac | created_at | ntp_server |
expires_at | updated_at | time_zone |
online | created_by | smtp_address |
radius_acct_session_id | updated_by | rails_env |
radius_response | scratch | note |
radius_class_attribute | created_at | |
created_at | updated_at | |
updated_at | created_by | |
created_by | updated_by | |
updated_by | smtp_port | |
bytes_up | smtp_domain | |
bytes_down | smtp_username | |
pkts_up | smtp_password | |
pkts_down | cluster_node_id | |
usage_bytes_up | scratch | |
usage_bytes_down | log_rotate_hour | |
ldap_domain_id | log_rotate_count | |
radius_realm_server_id | ssh_port | |
ldap_domain_server_id | country_code | |
cluster_node_id | disable_hyperthreading | |
shared_credential_group_id | developer_mode | |
ip_group_id | sync_builtin_admins | |
account_group_id | delayed_job_workers | |
usage_plan_id | log_level | |
lock_version | max_forked_processes | |
hostname | soap_port | |
total_bytes_up | reboot_timestamp | |
total_bytes_down | reboot_time_zone | |
total_pkts_up | limit_sshd_start | |
total_pkts_down | limit_sshd_rate | |
radius_server_id | limit_sshd_full | |
radius_request | use_puma_threads | |
backend_login_at | ||
http_user_agent_id | ||
backend_login_seconds | ||
portal_login_at | ||
omniauth_profile_id | ||
encrypted_password | ||
encrypted_password_iv | ||
conference_id | ||
password |
custom_email | transient_group_membership | time_trigger |
---|---|---|
id | id | id |
name | ip_group_id | account_group_id |
from | mac_group_id | name |
subject | account_group_id | mon |
body | account_id | tues |
event | ip | wed |
note | mac | thurs |
created_by | reason | fri |
updated_by | expires_at | sat |
created_at | created_by | sun |
updated_at | updated_by | start |
send_to_account | created_at | end |
scratch | updated_at | note |
email_recipient | cluster_node_id | created_by |
include_custom_reports_in_body | max_connections_trigger_id | updated_by |
attachment_format | quota_trigger_id | created_at |
custom_event | time_trigger_id | updated_at |
delivery_method | snort_trigger_id | ip_group_id |
sms_gateway_id | hostname | mac_group_id |
reply_to | radius_group_id | scratch |
ldap_group_id | flush_states | |
login_session_id | flush_dhcp | |
log_hits_trigger_id | flush_arp | |
flush_states | flush_vtas | |
flush_dhcp | infrastructure_area_id | |
flush_arp | previous_infrastructure_area_id | |
flush_vtas | duration | |
vulner_assess_trigger_id | current_dwell | |
previous_dwell |
log_hits_trigger | snort_trigger | max_connections_trigger |
---|---|---|
id | id | id |
ip_group_id | ip_group_id | ip_group_id |
mac_group_id | name | name |
name | duration | max_connections |
note | note | duration |
log_file | created_by | note |
duration | updated_by | created_by |
max_hits | created_at | updated_by |
window | updated_at | created_at |
scratch | scratch | updated_at |
created_by | mac_group_id | scratch |
updated_by | flush_states | mac_group_id |
created_at | flush_dhcp | flush_states |
updated_at | flush_arp | flush_dhcp |
flush_states | flush_vtas | flush_arp |
flush_dhcp | flush_vtas | |
flush_arp | max_duration | |
flush_vtas | max_mb | |
period | ||
active_or_expired | ||
max_duration_logic | ||
max_mb_logic |
quota_trigger | health_notice | cluster_node |
---|---|---|
id | id | id |
account_group_id | cluster_node_id | name |
name | name | iui |
usage_mb_down | short_message | database_password |
usage_mb_down_unit | long_message | note |
usage_mb_up | cured_short_message | created_by |
usage_mb_up_unit | cured_long_message | updated_by |
up_down_logic_operator | severity | created_at |
note | cured_at | updated_at |
created_by | created_at | ip |
updated_by | updated_at | ssh_public_key |
created_at | created_by | scratch |
updated_at | updated_by | heartbeat_at |
radius_group_id | fleet_node_id | data_plane_ha_timeout_seconds |
ldap_group_id | node_mode | |
period | cluster_node_team_id | |
unlimited_period | wal_receiver_pid | |
duration | wal_receiver_status | |
unlimited_duration | wal_receiver_receive_start_lsn | |
scratch | wal_receiver_receive_start_tli | |
ip_group_id | wal_receiver_received_lsn | |
mac_group_id | wal_receiver_received_tli | |
flush_states | wal_receiver_latest_end_lsn | |
flush_dhcp | wal_receiver_slot_name | |
flush_arp | wal_receiver_sender_host | |
flush_vtas | wal_receiver_sender_port | |
wal_receiver_last_msg_send_time | ||
wal_receiver_last_msg_receipt_time | ||
wal_receiver_latest_end_time | ||
op_cluster_node_id | ||
priority | ||
auto_registration | ||
permit_new_nodes | ||
auto_approve_new_nodes | ||
pending_auto_registration | ||
pending_approval | ||
control_plane_ha_backoff_seconds | ||
data_plane_ha_enabled | ||
upgrading | ||
enable_radius_proxy |
aged_ar_penalty |
---|
id |
name |
amount |
days |
suspend_account |
note |
created_at |
updated_at |
created_by |
updated_by |
custom_email_id |
scratch |
record_type |
days_type |
Use Cases
Slack Integration: Notification when an admin is created or deleted
Procedure:
- Use Slack guide to create a new app, and configure incoming webhooks.
Navigate to Services-->Notifications and create a new webhook target Insert the webhook address from your slack app as the base URL.
Create a webhook for created admins. An example body is:
{ "attachments": [ { "fallback": "Admin Created on <%= DeviceOption.active.domain_name %>.", "color": "#36a64f", "pretext": "A New Administrator has been created", "author_name": "FQDN: <%= DeviceOption.active.domain_name %>", "author_link": "https://<%= DeviceOption.active.domain_name %>/admin/", "title": "Created Admin: <%= admin.login %>", "text": "*Created by:* <%= admin.created_by %>", "fields": [ { "title": "Priority", "value": "Medium", "short": false } ], "footer": "Slack API" } ] }
Create a webhook for deleted admins An example body is: (notice the use of <%= admin_hash %> because the record has been deleted.)
{
"attachments": [
{
"fallback": Admin Deleted on <%= DeviceOption.active.domain_name %>.",
"color": "#FF0000",
"pretext": "An Administrator has been deleted",
"author_name": "FQDN: <%= DeviceOption.find_by(active: 'true').domain_name %>",
"author_link": "https://<%= DeviceOption.find_by(active: 'true').domain_name %>/admin/",
"title": "Deleted Admin: <%= admin_hash[:login] %>",
"text": "*Deleted by:* <%= admin_hash[:updated_by] %>",
"fields": [
{
"title": "Priority",
"value": "High",
"short": false
}
],
"footer": "Slack API"
}
]
}
- Create a notification action for created admins.
- Choose Event Type: Watch Scaffold
- Choose Watched Model: Administrators
- Select: Watch Create
- Choose the Admin Created Webhook under actions
- Create a notification action for deleted admins.
- Choose Event Type: Watch Scaffold
- Choose Watched Model: Administrators
- Select: Watch Delete
- Choose the Admin Deleted Webhook under actions
- Navigate to System-->Admins, and create a new admin. Then delete the new admin.
The channel configured in your Slack app will have messages posted via the rXg Notification Actions subsystem.
Location Based Crowding Notifications
Procedure:
- Navigate to Network :: Location
Create or edit existing location areas.
Edit individual areas and set crowd event thresholds. Thresholds can be set at region, floor, and site levels.
Navigate to Services :: Notifications
Create a notification action and select desired messages, webhooks and/or health notices to trigger.
Push Account To Remote rXg On Create
Procedure:
- Navigate to Services :: Notifications
Create a new Notification Action
- Event Type set to Watch Scaffold
- Watched Model set to Accounts
- Check the Watch Create checkbox
- Click Create.
Create a new Webhook Target
- Input a Name
- The base url will be https://FQDN\_of\_remote\_system/admins/scaffolds/
- Select body format, JSON in this case, and Body Encoding as RAW
- Add Webhook Property, Kind = Query Paramater, Key = api_key, the value will be the API key of an admin on remote system
- Click Create
Create a new Webhook
- Input a name
- Select Notification action created in step 1
- Select the webhook target created above
- Set path to accounts/create.json
- Set Method to POST
- Enter code into body (example below), click create.
<%
# get remote usage plan hash
result = HTTParty.post('https://FQDN_of_remote_system/admin/scaffolds/usage_plans/index.xml',
body: {:api_key=>"REMOTE_ADMIN_API_KEY",
:search=>account.usage_plan.try(:name)})
up = result["usage_plans"].try(:first)
# get remote account group hash
result = HTTParty.post('https://FQDN_of_remote_system/admin/scaffolds/account_groups/index.xml',
body: {:api_key=>"REMOTE_ADMIN_API_KEY",
:search=>account.account_group.try(:name)})
ag = result["account_groups"].try(:first)
# varible for device creation
count = 1
acct_hash = account.attributes
# remove attrs we dont want to push
acct_hash.delete("id")
acct_hash.delete("usage_plan_id")
acct_hash.delete("account_group_id")
acct_hash.delete("type")
acct_hash.delete("created_at")
acct_hash.delete("updated_at")
acct_hash.delete("created_by")
acct_hash.delete("updated_by")
acct_hash.delete("mb_up")
acct_hash.delete("mb_down")
acct_hash.delete("crypted_password")
acct_hash.delete("salt")
# make temporary password
acct_hash["password"] = acct_hash["password_confirmation"] = acct_hash["pre_shared_key"]
# add usage plan and do_apply_plan to hash if found on remote system
if up
acct_hash["usage_plan"] = up["id"]
acct_hash["do_apply_usage_plan"] = 1
end
# add account group to hash if found on remote system
if ag
acct_hash["account_group"] = ag["id"]
end
# add all devices to account hash
acct_hash["devices"] = {}
account.devices.each do |device|
acct_hash["devices"]["device#{count.to_s}"] = {
"name" => device.name,
"mac" => device.mac
}
count += 1
end
%>
{
"record": <%= acct_hash.to_json %>
}
CRM Integration
This example will explore integrating the rXg with the community edition of vTiger CRM. This case demonstrates using an API requiring a multistep login process, and use of a disposable session key rather than static credentials.
Procedure:
- The community edition of vTiger uses a combination of a challenge token, username, and access key to generate an expiring session key to be used with API calls. Create a custom data key under System :: Portals as a place to store the key.
- The only necessary field to populate is the name.
- Create a notification action to periodically get the session key, and perform a log in to the CRM.
- Set the event type to periodic.
- Choose a time within the session key expiration (the webhook will contain logic to determine if a refresh is necessary).
- Create a webhook target for the CRM.
- Add an HTTP header of "Content-Type": "application/x-www-form-urlencoded"
- Create a webhook that uses embedded ruby to store the current session key in the previously defined custom data key. This example looks at the age of the current key to see if a new key is necessary before executing.
- Choose the previously created notification action.
- Choose the CRM webhook target.
- Example Body:
<%
api_key = CustomDataKey.find_by(name: 'api_key')
if api_key.value_string.blank? || 30.minutes.since > api_key.updated_at
query = {
operation: "getchallenge",
username: "username",
}
resp = HTTParty.get(webhook_target.base_url, query: query)
token = JSON.parse(resp.body)['result']['token']
access_key = Digest::MD5.hexdigest(token + 'access_key_from_GUI')
body = {
operation: "login",
username: "username",
accessKey: access_key,
}
login = HTTParty.post(webhook_target.base_url, body: body)
session_id = JSON.parse(login.body)['result']['sessionName']
api_key.value_string = session_id
api_key.save!
end
raise DoNotSendError
%>
- Create a notfication action to trigger when a new account is created.
- Choose the event type: Watch Scaffold
- Choose the watched model: Accounts
- Check: Watch Create
- Create a webhook to create the account on the CRM.
- Select the previously created notification action.
- Choose the CRM webhook target.
- Set the method to POST
- Example Body:
<%=
{
operation: "create",
sessionName: CustomDataKey.find_by(name: 'api_key').value_string,
elementType: "Contacts",
element: {
firstname: record_hash["first_name"],
lastname: record_hash["last_name"],
assigned_user_id: "20x4",
}.to_json
}.to_query
%>
- Because vTiger CRM expects the body of the HTTP POST to be url-encoded the body is enclosed in ERB tags "<%= ... %>" so certain methods can be used to make formatting easier.
## Webhook to retrieve System Info
In this example will show how to setup a Webhook to push System Info on a periodic interval.
Procedure:
- Create a new Notification Action
- Populate the name field with the desired name.
- Set the Event Type field to Periodic.
- Specify how often the action should run using the Period field. Default is 5 minutes.
- Click Create.
2. Create a new Webhook Target
- Populate the name field with the desired name.
- Specify the URL of the target using the Base URL field.
Click Create.
- Create a new Webhook
Populate the name field with the desired name.
Use the Notification Actions field to select the notification action created in step 1.
Select the webhook target created in step 2 in the Webhook Target field.
Set the path in the Path field.
The Body field is where we will put our payload.
<%=
SystemInfo.first.attributes.to_json
%>
- Click Create.
This will pass the following information.
{
"id": 1048577,
"cluster_node_id": null,
"baseboard_asset_tag": "Not Specified",
"baseboard_manufacturer": "Intel Corporation",
"baseboard_product_name": "440BX Desktop Reference Platform",
"baseboard_serial_number": "None",
"baseboard_version": "None",
"bios_vendor": "Phoenix Technologies LTD",
"bios_version": "6.00",
"chassis_asset_tag": "No Asset Tag",
"chassis_manufacturer": "No Enclosure",
"chassis_serial_number": "None",
"chassis_type": "Other",
"chassis_version": "N/A",
"disk_device": "NECVMWar VMware SATA CD00 1.00",
"hostname": "rxg.example.com",
"os_arch": "amd64",
"os_branch": "RELEASE",
"os_kernel": "FreeBSD 12.2-RELEASE-p9 #16 476551a338d",
"os_name": "FreeBSD",
"os_release": "12.2-RELEASE-p9 #16",
"os_version": "12.2",
"processor_family": "Unknown",
"processor_frequency": "2300 MHz",
"processor_manufacturer": "GenuineIntel",
"processor_version": "Intel(R) Xeon(R) D-2146NT CPU @ 2.30GHz",
"rxg_build": "12.999",
"system_manufacturer": "VMware, Inc.",
"system_product_name": "VMware Virtual Platform",
"system_serial_number": "VMware-56 4d fd 29 e4 1a c1 4e-a2 60 81 57 54 ff dd 51",
"system_uuid": "29fd4d56-1ae4-4ec1-a260-815754ffdd51",
"system_version": "None",
"disk_total_gb": 111,
"memory_free_mb": 3874,
"memory_total_mb": 8192,
"memory_used_mb": 4317,
"processor_count": 4,
"uptime": 85371,
"load_avg_15m": "0.78",
"load_avg_1m": "1.09",
"load_avg_5m": "0.84",
"processor_temp": "0.0",
"bios_release_date": "2018-12-12",
"booted_at": "2021-08-30T08:37:23.000-07:00",
"created_by": "rxgd(InstrumentVitals)",
"updated_by": "rxgd(InstrumentVitals)",
"created_at": "2021-08-11T08:38:58.800-07:00",
"updated_at": "2021-08-31T08:20:14.808-07:00",
"rxg_iui": "4 2290 8192 111 ZKORHJVPDUQUZUNIBEWLHDFQ GZQQJUTGUDOIFDNTDUFQSKTW NLDQYHFARJWE",
"system_family": "Not Specified",
"fleet_node_id": null
}
Backend Scripts
The backend script allows the operator to write custom ruby scripts that can be used for things like interacting with mobile applications or performing a configuration change on a regular schedule. From the Notification Actions scaffold you can choose a trigger for the script from the drop down list. Some examples included manual, periodic, errors, and thresholds.
Big Red Button Mobile Application
This example will show how to setup a backend script that can be triggered by an API call executed by a mobile application which is available in the Apple and Google Play app stores.
This example assumes that you have an existing WLAN created under the WLANs scaffold with a record name of arena.
Procedure:
1) Browse to Services >> Notifications >> Backend Scripts 2) Click Create New 3) Name the backend script toggle_ssid. 4) Paste the following script into the body and click create.
def toggle_ssid wlan = Wlan.find_by(name: 'arena') ssid = wlan.ssid
if ssid == 'basketball_arena' wlan.ssid = 'hockey_arena' else wlan.ssid = 'basketball_arena' end
wlan.save! end
toggle_ssid
puts 'ssid toggled successfully'
5) Browse to Services >> Notifications >> Notification Actions 6) Click Create New 7) Name the notification action toggle_ssid. 8) Set the event type field to Manual. 9) Select toggle_ssid from the available scripts in the list.
Install the rXg Action Button Mobile App
Apple: https://apps.apple.com/us/app/rxg-action-button/id1483547358 Android: https://play.google.com/store/apps/details?id=net.lok.aidan.rxg_action_button
1) On the rXg browse to System >> Admins 2) Next to your admin account, click on the API Keys link. 3) Click Create New 4) Provide the API Key a name and click Create.
5) You will be presented with several QR codes. Make sure to leave this screen up.
6) From the mobile app, click Scan QR Code.
7) Scan the QR code labeled JSON. 8) Click Login With Saved Credentials
9) Set the action to toggle_ssid 10) Click on the slider to enable the button.
Now, simply press the red action button to toggle the SSID from basketball_arena to hockey_arena. These changes will be pushed to the wireless controller via config sync.
This is a very simple example of what can be done using a combination of a mobile application and the rXg backend scripts.
Conference Tool
Conference Tool Prerequisites
- Infastructure devices must be in sync.
- Any switches that contain switch ports that are tied to location areas need to be in sync.
- The wireless controller must also be in sync so the system can create SSID's that will be broadcast in the conference areas.
- Create VLAN interfaces and Network addresses.
- Create IP groups for each Network address that was created.
- Create Conference Options.
- Create Location Areas and assign switch ports/AP's.
- Switches and WLAN controllers must be in sync to fully work with the Conference Tool. To make sure they are in sync, navigate to Network::Wired and Network::Wireless to check the status of the devices. The "Config sync status" field should be green. See below images.
- Create VLAN interfaces and Network addresses. This step creates the networking that will be used for conferences. There are two types of networks that can be created. Per-user networks which will put each device in it's own VLAN (or a smaller group of devices in each VLAN if there are not enough VLANs for each device), or we can create a network that is contained in a single VLAN so that devices may communicate with each other. In either case navigate to Network::LAN.
To create a Per-user network first create a new VLAN Interface. Give it a name, select the Physical interface. Set the VLAN ID, which will be the starting VLAN. For this example we will set the Ratio to 4, this means that we will put 4 subnets we create in the next step into each VLAN. Click create.
Next create a new Network Address. Give it a name, select the VLAN from the previous step in the VLAN field. Specify the IP address using CIDR notation in the IP field. In this example there are going to be 128 /30 addresses created. When creating the networking, the operator should take care to create network address space that is large enough to contain enough addresses for the number of devices that are expected to connect to any given conference. For these addresses it is not necessary to check the Create DHCP Pool box, as the system will create the DHCP pool when the conference is active. Create New should be selected in the IP Group, which will take care of Step 3 as well. Click Create.
For non Per-User networks, create a new VLAN Interface, give it a name, select the Physical interface. Set the VLAN ID, which will be the starting VLAN. For non Per-User networks the Autoincrement field should be set to none, and the ratio left at 1. Click create.
Next create a new Network Address. Give it a name, select the VLAN from the previous step in the VLAN field. Specify the IP address using CIDR notation in the IP field. In this example we are creating a single /24 network that will be on VLAN 3500 which was created in the previous step, so make sure Autoincrement is set to 1. When creating the networking, the operator should take care to create network address space that is large enough to contain enough addresses for the number of devices that are expected to connect to any given conference. For these addresses it is not necessary to check the Create DHCP Pool box, as the system will create the DHCP pool when the conference is active. For this example we will not select Create New for the IP Group and will manually create the IP group. Click Create.
- Create IP groups for each Network address that was created. In the previous step one network was created with the create new IP group option selected and one was not. To manually create the IP group for the 2nd network in this example navigate to Identities::Groups and create a new IP Group. Give it a name, and select the Address in the Addresses field from the previous step. Leave everything else default and click create. Note a policy should not be selected when creating the IP Group as the system will create and assign a policy to the group as needed.
- Create Conference Options. Navigate to Services::Conference Tool and create a new Conference Option. Give it a name, and select the admin roles that are allowed to access the conference tool. Select the VLANs that the Conference Tool has access to. Leave any other settings as the defaults and click Create.
- Create Location Areas and assign switch ports/AP's. For this step a location area should be created for each conference space and the switch ports and AP's that are located in that physical space should be added. Create a new Location Area, give it a name, and select the AP's in this space in the Conference APs field and any switch ports in the Conference Ports field. Click Create. Repeat for each area. Lastly edit the Conference Option created in the previous step and select the Location Areas that have been created.
The Conference Tool is now ready to be used after completing these steps.
IoT Hubs
An entry in the IoT Hubs scaffold defines a device capable of controlling IoT devices. The rXg supports two controllers currently, RUCKUS IoT and RG Nets Piglet. The RUCKUS IoT (RIoT) controller is a virtualized software application that connects to RUCKUS IoT-enabled access points to provide support for BLE and ZigBee devices. One RIoT application per 500 IoT devices is the typical deployment model. RG Nets Piglet runs on a Raspberry Pi 4 and supports multiple protocols. One Piglet per account is the typical deployment model.
IotHubs
The online field when green, this indicates that the Iot Websocket Client is running and subscribed to streaming changes from this device. If red, the websocket client is not subscribed to streaming changes, so the state of iot entities may not accurately reflect the actual, current state.
The OS field indicates the version of the piglet software running on the IotHub.
The HA version indicates the version of home_assistant running on the IotHub.
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 the IP address of the Iot Hub.
The Port field is used to change ssh port, default is 22.
The Api Port field sets the API port for the Pi, default is 8123.
The Username field is used to set the username for the IotHub.
The Password field is used to set the password for the IotHub.
The Monitor state changes box if checked idndicates the websocket client should subscribe to streaming changes from this IotHub.
The Iot hub profile field is currently reserved for future use.
The Pms property field is optional, used to select the PMS property that the IotHub is associated with.
The Pms room field is optional, used to select the PMS room that the IotHub is associted with.
IotHubProfiles
Reserved for future use.
IotGroups
IotGroups are used to logically group IotHubs, IotEntities, and nested IotGroups. In addition, admin role access is granted at the IotGroup level. At a minimum, you will need to define an IotGroup that consists of the IotHubs you will want to control and assign the appropriate admin role access. Otherwise, IotHubs will not be populated on the iot hub dashboard in the operator portal due to lack of privileges.
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 Description 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 Group type field is reserved for future use.
The Admin roles field allows the operator to select which admin roles should have access to the group.
The Iot hubs field allows the operator to select the IotHubs included in the group.
The Iot entities field allows the operator to select which IotEntities are included in the group.
The Iot groups field is the nested IotGroups for the group.
IotEntities
IotEntities are the devices that are controlled and/or monitored by an IotHub. They can be lights, switches, sensors, or any supported IoT device. These are typically Z-Wave or Zigbee devices, but there are many different types of IoT control. These entities will be populated during an Import Entities for each hub. If you add devices after the initial import, you will want to run the import entities again.
The Iot type field is used to specify the type of entity, light, sensor, binary_sensor, etc.
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 Description 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 Is property controlled field is reserved for future use.
The State field is the last recored state of this entity, for example 'on' for a light.
The Iot actions field is reserved for future use.
The Iot hub field indicates the IotHub that this entity is associated with.
vRIoT Integration
The following section will outline the process of attaching RUCKUS vRIoT as an IoT hub in rXg and setup the MQTT service.
Add vRIoT as IoT Hub
- Browse to Services >> IoT Hubs
- In the IoT Hubs scaffold, click Create New
- Name the controller
- Set the Model dropdown to RUCKUS IoT Controller
- Add the IP address of the vRIoT server to the host field
- Provide a username and password to access the vRIoT server
- Press Create
- In the IoT Hubs scaffold, click Create New
- Click Import Entities link to complete the process.
Setup MQTT on the vRIoT Server
- On the vRIoT server, Browse to Admin >> Plugins
- From the dropdown, select Controller Data Stream
- Press the Activate button
- Configure the controller data stream as follows:
MQTT Broker IP: 127.0.0.1
MQTT Broker Port: 1883
MQTT Publish Topic: /events
Device Reporting: Yes
Device Reporting Topic: /events
- To confirm the MQTT service is working, SSH to the rXg and type
tail -f /var/log/mqtt_subscriber_iot.log
to check for activity.
RADIUS
The RADIUS view presents the scaffolds associated with configuring the rXg integrated RADIUS server.
Centralized Infrastructure Device AAA Server
The rXg identity database may be used as a credential store for rXg units or other third party devices via the RADIUS protocol. One common use of the rXg RADIUS server is to serve as a central credential database for administrative access to infrastructure equipment. For example, most VLAN "smart" switches and "enterprise" wireless access points may be configured to look to a RADIUS server for authenticating administrative access. Using the integrated rXg RADIUS server as a central credential store for infrastructure is a simple and effective way to reduce the complexity that is usually associated with networks that have a large number of devices.
Configuring rXg For Centralized Infrastructure Device AAA Server
Procedure: 1. Create an Account Group that will be tied to Administrator Account(s) 2. Create a policy for Administrator Account(s) Account Group
Check the AAA Account Group in the Account group section.3. Create a WAN Target that contains the public IP the radius request will come from. 4. Edit Radius Server Options add WAN target previously created. 5. Create a RADIUS realm and attach the policy created from the Administrator Account(s). 6. Create a new Account that will contain the credentials.
Attach account to the policy for Administrator Account(s)7. Point remote device to the rXg RADIUS server.
- Navigate to Identities-->Groups and create a new Account Group.
- Navigate to Policies-->Captive Portal and create a new Policy. Enter a name for the new policy and check the Account Group created in the previous step.
- Create a new WAN Target or edit existing WAN Target by navigating to Identities-->Definitions. Enter the IP(s) that should be allowed access to the Radius Server.
- Edit the RADIUS Server Options by navigating to Services-->RADIUS and check the WAN Target. Click Update.
- Create a new RADIUS Server Realm and select the policy that was created for the Administator account(s). Click Create.
- Create a new Account by navigating to Identities-->Accounts, Enter the Login name and password. Under Provision set the Group to the Account Group created previously. A First and Last name will also need to be provided along with an email address.
- Point the device to use the RADIUS server running on the rXg, set the primary IP address of the rXg as the AAA server, and adjust the ports if necessary. The key can be copied from the Radius Server Options on the rXg.
Subscriber Roaming
Another common use of the integrated rXg RADIUS server is to share a single centrally located end-user database amongst a set of geographically diverse RADIUS NAS capable devices. For example, "smart" access points, DSLAMs and even modem banks may be configured to use RADIUS to use an rXg with the RADIUS server enabled as a credential store. Using a single unified credential store across devices that controls access to multiple media helps control operational costs.
In many cases, the RADIUS NAS may also be configured for forced browser redirect of unauthenticated end-users to the rXg captive portal. This enables end-user self-provisioning and further reduces operational overhead. Since the rXg billing mechanisms are fully integrated into with the RADIUS server enabling operators to easily bill end-users for access to a diverse set of media.
The rXg integrated RADIUS server may also be used as a mechanism to loosely federate multiple rXg units. RG Nets recommends the deployment of the rXg clustering mechanism with an rXg cluster controller for unified and simplified clustering of multiple rXg units. However, for certain special cases, it may be more appropriate to use the RADIUS server of an rXg node or an rXg cluster controller along with the RADIUS NAS of multiple other rXgs to create a federation of rXg devices that share a single database.
One rXg unit is then dedicated to being the federation master. The captive portal web application server and end-user database are centrally stored on the federation master. The federation nodes are configured to authenticate using the RADIUS NAS clients and the rXg federation master is configured to be a RADIUS server.
Enterprise NAC
The rXg integrated RADIUS Server can be used to as a centralized AAA server for enterprise wired and wireless networks. Edge infrastructure devices are configured as access servers with port control enabled. Both username/password tuples and MAC address authentication credentials are supported. The rXg can proxy authentication to an external LDAP or RADIUS server (discussed later in this manual page) and/or check the local database.
If the local database is used then the operator may choose to create accounts for each employee and set a password. Alternatively, the administrator can use MAC address device authentication. To accomplish this, the operator will need to populate an account with desired MAC addresses. In either case, the account(s)should be associated with an account group. The account group also needs to be associated to a policy that is selected under a RADIUS Server Realm's matching options. By associating VLAN(s) to the RADIUS Server Realm , an operator can control what network(s) enterprise owned devices are assigned.
For example, in the packet exchange below, the Calling-Station-ID
attribute contains the MAC Address of the requesting device. The highest-priority policy will be used to determine which RADIUS Server Realm the device matches. The Tunnel-Private-Group-ID
attribute in the Access-Accept packet shows the VLAN assigned to this device.
14:38:33.381021 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto UDP (17), length 206)
10.103.254.4.56792 > 10.103.254.1.1812: [udp sum ok] RADIUS, length: 178
Access-Request (1), id: 0xe5, Authenticator: 2b9a4726041df0639dcc5f8574c30f5a
User-Name Attribute (1), length: 14, Value: 449160ece7fa
0x0000: 3434 3931 3630 6563 6537 6661
User-Password Attribute (2), length: 18, Value:
0x0000: a0e8 7cc3 4eb8 c07f 2322 714c a2e7 416e**Calling-Station-Id Attribute (31), length: 19, Value: 44-91-60-EC-E7-FA** 0x0000: 3434 2d39 312d 3630 2d45 432d 4537 2d46
0x0010: 41
NAS-IP-Address Attribute (4), length: 6, Value: 10.103.254.4
0x0000: 0a67 fe04
Called-Station-Id Attribute (30), length: 32, Value: D4-68-4D-2A-39-F0:SomeSSID
0x0000: 4434 2d36 382d 3444 2d32 412d 3339 2d46
0x0010: 303a 4b61 7272 6963 6b48 6f75 7365
Service-Type Attribute (6), length: 6, Value: Framed
0x0000: 0000 0002
NAS-Port-Type Attribute (61), length: 6, Value: Wireless - IEEE 802.11
0x0000: 0000 0013
NAS-Identifier Attribute (32), length: 19, Value: D4-68-4D-2A-39-F8
0x0000: 4434 2d36 382d 3444 2d32 412d 3339 2d46
0x0010: 38
Vendor-Specific Attribute (26), length: 20, Value: Vendor: Unknown (25053)
Vendor Attribute: 3, Length: 12, Value: KarrickHouse
0x0000: 0000 61dd 030e 4b61 7272 6963 6b48 6f75
0x0010: 7365
Message-Authenticator Attribute (80), length: 18, Value: .,H..-..S@.)..X.
0x0000: 842c 481d 8a2d 8c03 5340 0c29 deeb 5881
14:38:33.414314 IP (tos 0x0, ttl 64, id 6773, offset 0, flags [none], proto UDP (17), length 74)
10.103.254.1.1812 > 10.103.254.4.56792: [bad udp cksum 0x111c -> 0x598a!] RADIUS, length: 46
Access-Accept (2), id: 0xe5, Authenticator: d6f41b864e670829842982228b59649e
Class Attribute (25), length: 8, Value: Family
0x0000: 4661 6d69 6c79
Tunnel-Medium-Type Attribute (65), length: 6, Value: Tag[Unused] 802
0x0000: 0000 0006**Tunnel-Private-Group-ID Attribute (81), length: 6, Value: 2002**0x0000: 3230 3032
Tunnel-Type Attribute (64), length: 6, Value: Tag[Unused] VLAN
0x0000: 0000 000d
The enterprise NAC functionality can be used to augment other functions of the rXg. For instance, some WLAN controllers proxy RADIUS access-requests through the controller for client authentication, while others send the requests directly from each AP. Because the rXg utilizes ACLs to limit access to the RADIUS server function, the operator should utilize RADIUS MAC authentication on switchports to automate servicing access-requests from many APs.
Procedure:
- Create AP managment VLANs
- Create an IP group for AP Managment VLANs
- Create a policy for AP Management IP group
- Add AP Management policy to RADIUS Server Options scaffold
- Create a MAC group containing a wildcard of the OUIs of Access Points
- Attach MAC group to a policy
- Create a RADIUS realm for the AP MAC group policy
- Attach AP Management VLANs
- Enable RADIUS MAC authentication bypass on switch ports
DVLAN for Large Public Venues
The rXg incorporates intelligent VLAN assignment in the RADIUS Server. A RADIUS Server Realm with the per-device setting is used for guest, quarantine and onboarding networks where true device isolation is desired. This mechanism is often used a large public venues so that event attendees can be split across operator chosen VLANs. Optionally each device can be assigned a /30 network. To accomplish this, the operator will need to create a RADIUS Server Realm matching a policy, or attribute pattern, and select per-account or per-device in the Dynamic VLANs sharing menu. To enable microsegmented L3s or L2s for attendees, VLANs with proper auto-increment, and ratio settings should be implemented. VLAN re-use can be used in LPVs, where capacity exceeds available VLANs. This allows for high-density deployments, with minimal broadcast domains.
For example, in the packet exchange below, theCalled-Station-ID
attribute contains the AP Radio MAC Address, and SSID the client device requested. By using a attribute pattern match, the operator can have all devices requesting this WLAN match this RADIUS Realm. The rXg has a variety of built in attributes, and allows the operator to define custom attributes to match
14:38:33.381021 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto UDP (17), length 206)
10.103.254.4.56792 > 10.103.254.1.1812: [udp sum ok] RADIUS, length: 178
Access-Request (1), id: 0xe5, Authenticator: 2b9a4726041df0639dcc5f8574c30f5a
User-Name Attribute (1), length: 14, Value: 449160ece7fa
0x0000: 3434 3931 3630 6563 6537 6661
User-Password Attribute (2), length: 18, Value:
0x0000: a0e8 7cc3 4eb8 c07f 2322 714c a2e7 416e
Calling-Station-Id Attribute (31), length: 19, Value: 44-91-60-EC-E7-FA
0x0000: 3434 2d39 312d 3630 2d45 432d 4537 2d46
0x0010: 41
NAS-IP-Address Attribute (4), length: 6, Value: 10.103.254.4
0x0000: 0a67 fe04**Called-Station-Id Attribute (30), length: 32, Value: D4-68-4D-2A-39-F0:EventSSID**0x0000: 4434 2d36 382d 3444 2d32 412d 3339 2d46
0x0010: 303a 4b61 7272 6963 6b48 6f75 7365
Service-Type Attribute (6), length: 6, Value: Framed
0x0000: 0000 0002
NAS-Port-Type Attribute (61), length: 6, Value: Wireless - IEEE 802.11
0x0000: 0000 0013
NAS-Identifier Attribute (32), length: 19, Value: D4-68-4D-2A-39-F8
0x0000: 4434 2d36 382d 3444 2d32 412d 3339 2d46
0x0010: 38
Vendor-Specific Attribute (26), length: 20, Value: Vendor: Unknown (25053)
Vendor Attribute: 3, Length: 12, Value: KarrickHouse
0x0000: 0000 61dd 030e 4b61 7272 6963 6b48 6f75
0x0010: 7365
Message-Authenticator Attribute (80), length: 18, Value: .,H..-..S@.)..X.
0x0000: 842c 481d 8a2d 8c03 5340 0c29 deeb 5881
14:38:33.414314 IP (tos 0x0, ttl 64, id 6773, offset 0, flags [none], proto UDP (17), length 74)
10.103.254.1.1812 > 10.103.254.4.56792: [bad udp cksum 0x111c -> 0x598a!] RADIUS, length: 46
Access-Accept (2), id: 0xe5, Authenticator: d6f41b864e670829842982228b59649e
Class Attribute (25), length: 8, Value: Family
0x0000: 4661 6d69 6c79
Tunnel-Medium-Type Attribute (65), length: 6, Value: Tag[Unused] 802
0x0000: 0000 0006
Tunnel-Private-Group-ID Attribute (81), length: 6, Value: 2002
0x0000: 3230 3032
Tunnel-Type Attribute (64), length: 6, Value: Tag[Unused] VLAN
0x0000: 0000 000d
DVLAN Microsegmentation for Multi-Tenant and Hospitality
By configuring a RADIUS Server Realm in the rXg to use per-room, or per-guest VLANs, users can be dynamically assigned a microsegmented network. This enables users to have private LANs on a shared infrastructure, enabling property wide coverage of their personal network. Unique features such as screencasting, printing, etc., can happen via standard L2 protocols. To accomplish this, the operator will need to create a RADIUS Server Realm matching a policy associated to the desired account group , and select per-room in the Dynamic VLANs sharing menu.
For example, a hotel client would integrate the rXg with their existing PMS, and assign per-room VLANs to segment guests. This enables the guests to use services like screencasting in their rooms without the need to download an app. A shared office space environment would implement per-guest VLANs, and segment traffic from other guests, while making tasks like printing and file-sharing seamless.
An operator can associate a Bi-NAT pool to a policy, and utilize the per-room DVLAN mechanism to provide a "virtual Residential Gateway" or vRG. This enables end-users to manage their own port forwards for web-hosting, and gaming. In MDU or Dorm environments, this enables zero-operator intervention, and instant provisioning of typically complex configurations.
RADIUS Proxying
RADIUS Proxy Servers can be used in a variety of ways. By defining a RADIUS Proxy Server an operator can choose to proxy authentication, accounting, or all RADIUS packets to a remote RADIUS Server, LDAP Server, or PMS Server. By proxying authentication requests to a remote server, an operator can enable centralized credential management in distributed rXg deployments.
For example, the rXg can proxy ONLY RADIUS Accounting packets to an upstream device. This is useful in routed scenarios, where the rXg is not the head-end. This enables the operator to send user-name and IP/session information to upstream devices such as content filters, or firewalls.
An operator may also choose to proxy authentication requests against a configured LDAP Server. This enables 802.1x authentication directly against an LDAP server such as Microsoft Active Directory, without the use of Microsoft Network Policy Server (NPS).
RADIUS Proxy with RadSec
RadSec is a a protocol for transporting RADIUS datagrams over TCP and TLS. Standard RADIUS communications depend upon the unreliable transport protocol UDP, and lack security for large parts of the packet payload. RadSec provides a means to secure the communication between a RADIUS NAS and Server by utilizing Transport Layer Security (TLS). By utilizing RadSec, an operator can proxy incoming RADIUS requests securely to a centralized credential store.
To learn more about RADIUS, there are numerous web pages that provide background information on the RADIUS protocol. In addition, the O'Relly RADIUS (ISBN 0596003226) book provides a basic overview of the protocol. A good reference for how to use RADIUS in more complex environments is AAA and Network Security for Mobile Access: Radius, Diameter, EAP, PKI and IP Mobility (ISBN 0470011947).
Multiple PSK with Adtran vWLAN
AdTran supports multiple sets of tagged Tunnel-* RADIUS attributes where each set represents a 'guess' of what the end user may have entered into her device as the PSK. When a set of Tunnel-* attributes tagged with :1 are configured in the rXg, the rXg will automatically create additional sets of Tunnel-* attributes that represent additional possible Accounts the device may belong to. The rXg will create up to 24 total attribute sets. The AP will determine which set contains the correct PSK, and if it finds one, will allow the device to connect and start tagging the device traffic with the VLAN from the set that contained the correct PSK. Assuming 'Automatic Provisioning' is enabled in the account, the rXg will then automatically add the new device to the Account that corresponds to the VLAN from the attribute set.
Prerequisites
- Have Onboarding VLANs, associated to policy with a splash portal
- Have usage plan available for selection on splash portal
- Make sure the "Automatic Provision" checkbox is selected
- Have VLAN(s) available for registered accounts
- Have account group(s) for registered accounts associated to a policy with a landing portal
Configuration
- 1. Deploy vWLAN OVA
- vWLAN Appliance gets DHCP by default
- Login to vWLAN and add AP Licensing
- Either set Static IP on vWLAN, or add fixed-host address in DHCP
- Create "domain-name" DHCP Option , and attach to Global DHCP Option Group (Ex. Domain-Name = local)
- Create DNS Entry for apdiscovery.local to point to vWLAN controller (replace local with your domain name)
- Add vWLAN Controller to rXg wireless Infrastructure Devices
- Create an "Onboarding" RADIUS Realm and use an Attribute Pattern match since these devices would be unknown.
- Select your Onboarding VLANs, to ensure that users are presented the splash portal
- Create a Radius Realm for the policy of registered accounts
- - Select your Account VLANs
- Enable config sync on the vWLAN infrastructure device on the rXg
- Create a new WLAN choosing the following options
- Encryption: WPA2
- Authentication: Multiple PSK
- VLANs (Any associated with both realms)
- New RADIUS Server Attributes will be automatically created
- Create new RADIUS Server Attribute for onboarding
- Name: Tunnel-Password:1
- Value: onboarding (or whatever you want the onboarding PSK to be)
- Edit your Onboarding RADIUS Realm to respond with these attributes (notice the :1)
- Tunnel-Private-Group-Id:1 : %vlan_tag_assignment.tag%
- Tunnel-Type:1 : VLAN
- Tunnel-Medium-Type:1 : IEEE-802
- Tunnel-Password:1 : onboarding
- Edit your registered account RADIUS Realm to respond with these attributes (notice NO :1)
- Tunnel-Private-Group-Id : %vlan_tag_assignment.tag%
- Tunnel-Type : VLAN
- Tunnel-Medium-Type : IEEE-802
- Tunnel-Password : %account.pre_shared_key%
Dynamic PSK with RUCKUS virtual SmartZone (vSZ)
RUCKUS eDPSK enables an external AAA server to manage multiple PSKs associated with a single SSID. the rXg leverages eDPSK in conjunction with internal and external account management to deleiver person area networks (PANs) and virtual residential gateway (vRG) for MDUs.
Prerequisites
- Have Onboarding VLANs, associated to policy with a splash portal
- Have usage plan available for selection on splash portal
- Make sure the "Automatic Provision" checkbox is selected
- Have VLAN(s) available for registered accounts
- Have account group(s) for registered accounts associated to a policy with a landing portal
Configuration
- Deploy vSZ OVA, configure the following in the VM console:
- Configure vSZ in Essentials mode
- Set Static IP Address, or set DHCP Reservation
- Continue the vSZ deployment at web GUI -
https://{vSZ IP}:8443
- Add vSZ to rXg wireless Infrastructure Devices
- Create an "Onboarding" RADIUS Realm and use an Attribute Pattern match since these devices would be unknown.
- Select your Onboarding VLANs, to ensure that users are presented the splash portal
- Create a Radius Realm for the policy of registered accounts
- - Select your Account VLANs
- Enable config sync on the vWLAN infrastructure device on the rXg
- Create a new WLAN choosing the following options
- Encryption: WPA2
- Authentication: Multiple PSK
- VLANs (Any associated with both realms)
- Create new RADIUS Server Attribute for onboarding
- Name: Ruckus-DPSK
- Value: onboarding (or whatever you want the onboarding PSK to be)
- Edit your Onboarding RADIUS Realm to respond with these attributes
- Tunnel-Private-Group-Id : %vlan_tag_assignment.tag%
- Tunnel-Type : VLAN
- Tunnel-Medium-Type : IEEE-802
- Ruckus-DPSK : onboarding
- Edit your registered account RADIUS Realm to respond with these attributes
- Tunnel-Private-Group-Id : %vlan_tag_assignment.tag%
- Tunnel-Type : VLAN
- Tunnel-Medium-Type : IEEE-802
- Tunnel-Password : %account.pre_shared_key%
RADIUS Server Realms
An entry in the radius server realms scaffold creates a response realm that enables the rXg to respond to RADIUS requests.
One or more radius server realms are required in order to link RADIUS requests with attributes. Only one radius server realm is required if the network design requires that the same set of RADIUS attributes to be transmitted to all RADIUS requests.
Multiple radius server realms may be created in order to allow the rXg integrated RADIUS Server to respond with different RADIUS attributes depending upon the request. The most common usage scenario that requires the creation of two or more radius server realms is a network design that requires different VLANs or sets of VLANs to be assigned based on information present in the incoming RADIUS request. A RADIUS Access-Request will match at most a single RADIUS Server Realm
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 rank of a RADIUS server realm, allows the operator to designate multiple RADIUS realms with the same policy selection. If a RADIUS request matches multiple RADIUS realms, the highest ranking realm is used. This is typically used to override RADIUS realms when specific criteria is met, such as a user of a given policy connecting to a special SSID.
The policies field enables the operator to restrict this response realm to one or more sets of Identities. RADIUS Access-Request messages usually contain the MAC address of the end-user device. Thus a radius server realm may be restricted to answer RADIUS Access-Requests originating from end-user devices whose MAC addresses are present within MAC Groups and Account Groups. If no policies are enabled then the rXg will not restrict this response realm based on Identities but may still be restricted by other parameters such as attribute patterns.
The attribute patterns subsection enables the operator to restrict this response realm to RADIUS Access-Requests that contain the specified RADIUS attributes. One common use for this is mechanism is to restrict a response realm to only respond to RADIUS Access-Requests originating from end-user devices that are attaching to a specific SSID. This capability enables the operator associate respond with different RADIUS attributes depending upon the data in RADIUS Access-Request.
The dynamic VLANs section determines which VLANs will be passed from the rXg to the RADIUS NAS when a RADIUS Access-Accept message is sent. VLAN assignments are typically passed through RADIUS Attributes.
VLAN assignments are made either per-Device, per-Account, per-Guest, or per-Room. Using the per-Device setting tells the rXg to assign each MAC address that it sees a unique VLAN. The per-Device selection maximizes broadcast domain separation. The per-Account selection puts MAC addresses that belong to the same Account within the same VLAN. The per-Room and per-Guest selections puts MAC addresses that are associated with the same PMS Room or Guest name within the same VLAN.
One or more VLAN records must be configured and selected in order for the dynamic VLAN mechanism to be enabled. In most cases each RADIUS Server Realm will be associated with only a single VLAN record.
VLANs will be assigned to devices / accounts / PMS-Rooms per the above described selection until all available VLANs in the selected record are exhausted. If the Reuse VLANs checkbox is enabled then the VLANs configured in the VLAN will be reused if the VLANs in the record are exhausted. This setting is most often used in conjunction with the per-Device VLAN assignment setting as the number of devices will sometimes exceed the number of available VLANs.
The infrastructure devices setting enables the operator to tie this RADIUS Server Realm with an infrastruture device for the purpose of sending vendor specific instructions when VLANs change. This configuration is an absolute requirement when the dynamic VLAN capability is used with most wireless LAN controllers and wired switches.
The Proxy Servers field enables the operator to proxy incoming RADIUS packets to configured RADIUS Proxy Servers , LDAP Domains , or PMS Servers.
The Proxy Options enable an operator to choose what type of RADIUS packets to proxy, Accounting, Authentication, or both. By default, the rXg integrated RADIUS Server will only proxy 802.1x authentications. The Proxy MAC Auth selection enables the operator to also proxy MAC based authentications. The Replace username selection will override the "User-Name" attribute with the associated accounts login. If the Proxy Server is being used for authentication, the Create Account selection will create a local account on the rXg, and optionally apply a Usage Plan.
The attributes field defines one or more RADIUS attributes that will be appended to all RADIUS responses. Use this mechanism to send vendor specific attributes to the devices making RADIUS requests.
The Assume MAC auth option specifies that when an Account is located during RADIUS lookup and the request looks like a MAC auth request (i.e., the username looks like a MAC address) that we should treat the request as a MAC auth request and use the MAC address as the cleartext password instead of setting the NT-Password.
The Always perform Account lookup option ensures that an Account lookup occurs for the request while checking this realm, assuming it has not been performed already by a higher ranked realm. This is in contrast to the normal behavior where Account lookup is skipped unless there are Account Group-based Policies attached to the realm (or a higher ranked realm). This is necessary if performing MSCHAP authentication and the realm is being selected based on a RADIUS Attribute match pattern, rather than group membership. In this case the lookup is still necessary in order to set the NT-Password for the MSCHAP module.
RADIUS Proxy Servers
An entry in the RADIUS proxy servers scaffold defines a server that may be used to proxy requests to other remote RADIUS servers.
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 RADIUS server realms field determines which logical partitions of the RADIUS Server will proxy requests to THIS server.
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 priority field is used when multiple RADIUS proxy servers are associated with a RADIUS realm. The RADIUS proxy server with the highest priority is queried first. If the RADIUS proxy server with the highest priority does not respond within the window defined by the tries and timeout fields, the next highest priority server is queried. If no RADIUS proxy servers respond, the end-user is denied access.
The IP field specifies the IP address of the RADIUS server to be queried for credential validation.
The port field specifies the UDP port to use when sending the RADIUS request for credential validation. Similarly the accounting port field specifies the UDP port to use when sending the RADIUS accounting start, stop and intermediate updates. Leave these fields blank to use the defaults.
The secret field is the RADIUS shared secret. It is used to encode and decode messages being sent to and from the RADIUS server. This setting must match that of the RADIUS server in order for credential validation to operate.
If a server does not respond to a request within the timeout time, the server marks the request as timed out. After the configured number of tries , the server is marked as being "zombie", and the zombie period starts. The default timeout window is large because responses may be slow, especially when proxying across the Internet.
A server that is marked "zombie" will be used for proxying as a low priority. If there are live servers, they will always be preferred to a zombie. Requests will be proxied to a zombie server ONLY when there are no live servers. Any request that is proxied to a server will continue to be sent to that server until the server is marked dead. At that point, it will fail over to another server, if a live server is available. If the server does not respond to ANY packets during the zombie period , it will considered to be dead.
If status check is something other than "none", then the server will start sending status checks at the start of the zombie period. It will continue sending status checks until the server is marked "alive". These status packets are sent ONLY if the server is believed to be dead. They are NOT sent if the server is believed to be alive. They are NOT sent if this server is not proxying packets. If the server responds to the status check packet, then it is marked alive again, and is returned to use.
The check interval field configures the number of status checks in a row that the server needs to respond to before it is marked alive. If you want to mark a server as alive after a short time period of being responsive, it is best to use a small check interval , and a large value for answers to alive. Using a long check interval and a small number for answers to alive increases the probability of spurious fail-over and fallback attempts.
RADIUS layer "status checks" are used to see if a server is alive when status check is set to "Status-Server".
Some servers do not support status checks via the Status-Server packet. Others may not have a "test" user configured that can be used to query the server, to see if it is alive. For those servers, there is NO WAY of knowing when it becomes alive again. In this case, after the server has been marked dead, the revival interval must elapse before it is marked alive again, in the hope that it has come back to life. If it has NOT come back to life, the zombie period must elapse before marking it dead again. During the zombie period , all authentications will fail, because the server is still dead. There is nothing that can be done about this, other than to enable the status checks. e.g. if zombie period is 40 seconds, and revive interval is 300 seconds, then for 40 seconds out of every 340, or about 10% of the time, all authentications will fail. If the zombie period and revive interval configurations are set smaller, then it is possible for up to 50% of authentications to fail. We recommend enabling status check , and we do NOT recommend relying on revive interval. The revive interval is used ONLY if status check is set to "none".
If the server does not support Status-Server packets, then the proxying server can still send Access-Request or Accounting-Request packets with a pre-defined username. This behavior is enabled by setting status check to "Access-Request". This practice is NOT recommended, as it may potentially let users gain network access by using these "test" accounts. If it is used, we recommend that the server ALWAYS respond to these Access-Request status checks with Access-Reject. The status check just needs an answer, it does not need an Access-Accept. For Accounting-Request status checks, only the username needs to be set. The rest of the accounting attribute are set to default values. The server that receives these accounting packets SHOULD NOT treat them like normal user accounting packets.
RADIUS Server
The rXg internal credential database of users and tokens may be remotely accessed via the RADIUS protocol. Records in the RADIUS Server scaffold configure the behavior of the rXg RADIUS server.
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 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 secret field defines the RADIUS shared secret. This shared credential must be identical to one configured on the RADIUS NAS devices that will access this RADIUS server.
The auth port and acct port fields configure the ports that the RADIUS server will listen for requests on. In most cases, the RFC defined ports of 1812 and 1813 should be used as many RADIUS NAS devices are only able to connect to those ports.
The debug field configures the RADIUS server to log the contents of all request and response packets to the log file.
The certificate field specifies an alternate certificate chain to configure the RADIUS server with.
The WAN targets and policies fields determine the set of devices that are allowed to have access to the rXg integrated RADIUS server. By default the rXg has packet filtering rules in place that prevent access to the integrated RADIUS server. This ensures that no devices of any kind may access the RADIUS server unless the operator takes specific action to enable access.
Access to the rXg integrated RADIUS server for RADIUS NAS devices that are on the WAN is enabled by creating one or more WAN targets for the RADIUS NAS devices and then enabling the appropriate check boxes. RADIUS NAS devices on the LAN may be granted access by placing the IPs of the RADIUS NAS devices into an IP Group and then linking the IP Group into a Policy which may be selected here.
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.
RADIUS Server Attributes
The rXg integrated RADIUS server responds to RADIUS requests with RFC defined attributes. The operator may define additional attributes to be present in RADIUS responses by creating RADIUS Server Attribute records. Each record defines one additional attribute that will be presnet
The name configures the name of the RADIUS attribute that will be sent to the RADIUS NAS. The name must be agreed upon and configured identically on both the RADIUS server and the RADIUS NAS.
The value configures the value of the payload of the RADIUS attribute that will be sent to the RADIUS NAS in RADIUS server response. The value may be static (e.g., 'IEEE-802' for the 'Tunnel-Medium-Type' when configuring dynamic VLANs). Alternatively the value may be a dynamic value configured through substitution variables.
The RADIUS Server Realms field determines which RADIUS requests will contain the RADIUS Server Attribute defined by this record. More than one RADIUS Server Realm may be selected and thus the RADIUS Server Attribute defined by this record will be present in the responses to each of the defined realms.
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.
Most dynamic VLAN configurations require the following three attributes to be configured:
| Tunnel-Medium-Type
| 802
|
| Tunnel-Private-Group-ID
| %vlan_tag_assignment.tag%
|
| Tunnel-Type
| VLAN
|
Substitution
Payload fields may contain special keywords surrounded by % signs that will be substituted with relevant values. This enables the operator to deliver values stored in the database as part of the payload.
List of objects available:
Account Create | Usage Plan Purchase | Transaction: success/failure |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
ip_group | login_session | login_session |
login_session | usage_plan | merchant |
usage_plan | account | payment_method |
account | merchant_transaction | |
usage_plan | ||
account |
Credit Card Expiring | Coupon Redemption | Account Charge: success/failure/no response |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
login_session | coupon | login_session |
payment_method | login_session | payment_method |
usage_plan | usage_plan | response |
account | account | usage_plan |
account |
Trigger: Connections | Trigger: Quota | Trigger: DPI |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
login_session | login_session | login_session |
max_connections_trigger | quota_trigger | snort_trigger |
transient_group_membership | transient_group_membership | transient_group_membership |
account | account | account |
Trigger: Time | Trigger: Log Hits | Health Notice: create |
---|---|---|
cluster_node | cluster_node | cluster_node |
custom_email | custom_email | custom_email |
device_option | device_option | device_option |
login_session | login_session | health_notice |
time_trigger | log_hits_trigger | |
transient_group_membership | transient_group_membership | |
account | account |
Health Notice: cured |
---|
cluster_node |
custom_email |
device_option |
health_notice |
List of objects available for all associated record types:
Aged AR Penalty |
---|
cluster_node |
custom_email |
device_option |
aged_ar_penalty |
login_session |
payment_method |
usage_plan |
account |
List of attributes available for each object:
account | usage_plan | merchant |
---|---|---|
id | id | id |
type | account_group_id | name |
login | name | gateway |
crypted_password | description | login |
salt | currency | password |
state | recurring_method | test |
first_name | recurring_day | note |
last_name | variable_recurring_day | created_at |
automatic_login | updated_at | |
usage_plan_id | note | created_by |
usage_minutes | created_at | updated_by |
unlimited_usage_minutes | updated_at | signature |
usage_expiration | created_by | partner |
no_usage_expiration | updated_by | invoice_prefix |
automatic_login | time_plan_id | integration |
note | quota_plan_id | store_payment_methods |
logged_in_at | usage_lifetime_time | live_url |
created_at | absolute_usage_lifetime | pem |
updated_at | unlimited_usage_lifetime | scratch |
created_by | no_usage_lifetime | dup_timeout_seconds |
updated_by | recurring_retry_grace_minutes | |
mb_up | recurring_fail_limit | |
mb_down | prorate_credit | |
pkts_up | permit_unpaid_ar | |
pkts_down | pms_server_id | |
usage_mb_up | lock_devices | |
usage_mb_down | scratch | |
unlimited_usage_mb_up | max_sessions | |
unlimited_usage_mb_down | max_devices | |
company | unlimited_devices | |
address1 | unlimited_sessions | |
address2 | usage_lifetime_time_unit | |
city | max_dedicated_ips | |
region | pms_guest_match_operator | |
zip | recurring_lifetime_time | |
country | recurring_lifetime_time_unit | |
phone | unlimited_recurring_lifetime | |
bill_at | sms_gateway_id | |
lock_version | validation_method | |
charge_attempted_at | validation_grace_minutes | |
lock_devices | max_party_devices | |
relative_usage_lifetime | unlimited_party_devices | |
scratch | upnp_enabled | |
portal_message | automatic_provision | |
max_devices | conference_id | |
unlimited_devices | ips_are_static | |
max_sessions | base_price | |
unlimited_sessions | vtas_are_static | |
max_dedicated_ips | manual_ar | |
account_group_id | ||
email2 | ||
pre_shared_key | ||
phone_validation_code | ||
email_validation_code | ||
phone_validated | ||
email_validated | ||
phone_validation_code_expires_at | ||
email_validation_code_expires_at | ||
max_party_devices | ||
unlimited_party_devices | ||
nt_password | ||
upnp_enabled | ||
automatic_provision | ||
ips_are_static | ||
guid | ||
vtas_are_static | ||
account_id | ||
max_sub_accounts | ||
unlimited_sub_accounts | ||
approved_by | ||
approved_at | ||
pending_admin_approval | ||
wispr_data | ||
hide_from_operator |
payment_method | merchant_transaction | coupon |
---|---|---|
id | id | id |
account_id | account_id | usage_plan_id |
active | payment_method_id | code |
company | merchant_id | credit |
address1 | usage_plan_id | expires_at |
address2 | amount | note |
city | currency | created_by |
state | test | updated_by |
zip | ip | created_at |
country | mac | updated_at |
phone | customer | batch |
note | scratch | |
created_at | merchant_string | max_redemptions |
updated_at | description | unlimited_redemptions |
created_by | success | |
updated_by | response_yaml | |
scratch | created_at | |
customer_id | updated_at | |
card_id | created_by | |
nickname | updated_by | |
encrypted_cc_number | message | |
encrypted_cc_number_iv | authorization | |
encrypted_cc_expiration_month | hostname | |
encrypted_cc_expiration_month_iv | http_user_agent_id | |
encrypted_cc_expiration_year | account_group_id | |
encrypted_cc_expiration_year_iv | subscription_id | |
encrypted_first_name | ||
encrypted_first_name_iv | ||
encrypted_middle_name | ||
encrypted_middle_name_iv | ||
encrypted_last_name | ||
encrypted_last_name_iv | ||
cc_number | ||
cc_expiration_month | ||
cc_expiration_year | ||
first_name | ||
middle_name | ||
last_name |
login_session | ip_group | device_option |
---|---|---|
id | id | id |
account_id | policy_id | name |
radius_realm_id | name | active |
login | priority | device_location |
ip | note | domain_name |
mac | created_at | ntp_server |
expires_at | updated_at | time_zone |
online | created_by | smtp_address |
radius_acct_session_id | updated_by | rails_env |
radius_response | scratch | note |
radius_class_attribute | created_at | |
created_at | updated_at | |
updated_at | created_by | |
created_by | updated_by | |
updated_by | smtp_port | |
bytes_up | smtp_domain | |
bytes_down | smtp_username | |
pkts_up | smtp_password | |
pkts_down | cluster_node_id | |
usage_bytes_up | scratch | |
usage_bytes_down | log_rotate_hour | |
ldap_domain_id | log_rotate_count | |
radius_realm_server_id | ssh_port | |
ldap_domain_server_id | country_code | |
cluster_node_id | disable_hyperthreading | |
shared_credential_group_id | developer_mode | |
ip_group_id | sync_builtin_admins | |
account_group_id | delayed_job_workers | |
usage_plan_id | log_level | |
lock_version | max_forked_processes | |
hostname | soap_port | |
total_bytes_up | reboot_timestamp | |
total_bytes_down | reboot_time_zone | |
total_pkts_up | limit_sshd_start | |
total_pkts_down | limit_sshd_rate | |
radius_server_id | limit_sshd_full | |
radius_request | use_puma_threads | |
backend_login_at | ||
http_user_agent_id | ||
backend_login_seconds | ||
portal_login_at | ||
omniauth_profile_id | ||
encrypted_password | ||
encrypted_password_iv | ||
conference_id | ||
password |
custom_email | transient_group_membership | time_trigger |
---|---|---|
id | id | id |
name | ip_group_id | account_group_id |
from | mac_group_id | name |
subject | account_group_id | mon |
body | account_id | tues |
event | ip | wed |
note | mac | thurs |
created_by | reason | fri |
updated_by | expires_at | sat |
created_at | created_by | sun |
updated_at | updated_by | start |
send_to_account | created_at | end |
scratch | updated_at | note |
email_recipient | cluster_node_id | created_by |
include_custom_reports_in_body | max_connections_trigger_id | updated_by |
attachment_format | quota_trigger_id | created_at |
custom_event | time_trigger_id | updated_at |
delivery_method | snort_trigger_id | ip_group_id |
sms_gateway_id | hostname | mac_group_id |
reply_to | radius_group_id | scratch |
ldap_group_id | flush_states | |
login_session_id | flush_dhcp | |
log_hits_trigger_id | flush_arp | |
flush_states | flush_vtas | |
flush_dhcp | infrastructure_area_id | |
flush_arp | previous_infrastructure_area_id | |
flush_vtas | duration | |
vulner_assess_trigger_id | current_dwell | |
previous_dwell |
log_hits_trigger | snort_trigger | max_connections_trigger |
---|---|---|
id | id | id |
ip_group_id | ip_group_id | ip_group_id |
mac_group_id | name | name |
name | duration | max_connections |
note | note | duration |
log_file | created_by | note |
duration | updated_by | created_by |
max_hits | created_at | updated_by |
window | updated_at | created_at |
scratch | scratch | updated_at |
created_by | mac_group_id | scratch |
updated_by | flush_states | mac_group_id |
created_at | flush_dhcp | flush_states |
updated_at | flush_arp | flush_dhcp |
flush_states | flush_vtas | flush_arp |
flush_dhcp | flush_vtas | |
flush_arp | max_duration | |
flush_vtas | max_mb | |
period | ||
active_or_expired | ||
max_duration_logic | ||
max_mb_logic |
quota_trigger | health_notice | cluster_node |
---|---|---|
id | id | id |
account_group_id | cluster_node_id | name |
name | name | iui |
usage_mb_down | short_message | database_password |
usage_mb_down_unit | long_message | note |
usage_mb_up | cured_short_message | created_by |
usage_mb_up_unit | cured_long_message | updated_by |
up_down_logic_operator | severity | created_at |
note | cured_at | updated_at |
created_by | created_at | ip |
updated_by | updated_at | ssh_public_key |
created_at | created_by | scratch |
updated_at | updated_by | heartbeat_at |
radius_group_id | fleet_node_id | data_plane_ha_timeout_seconds |
ldap_group_id | node_mode | |
period | cluster_node_team_id | |
unlimited_period | wal_receiver_pid | |
duration | wal_receiver_status | |
unlimited_duration | wal_receiver_receive_start_lsn | |
scratch | wal_receiver_receive_start_tli | |
ip_group_id | wal_receiver_received_lsn | |
mac_group_id | wal_receiver_received_tli | |
flush_states | wal_receiver_latest_end_lsn | |
flush_dhcp | wal_receiver_slot_name | |
flush_arp | wal_receiver_sender_host | |
flush_vtas | wal_receiver_sender_port | |
wal_receiver_last_msg_send_time | ||
wal_receiver_last_msg_receipt_time | ||
wal_receiver_latest_end_time | ||
op_cluster_node_id | ||
priority | ||
auto_registration | ||
permit_new_nodes | ||
auto_approve_new_nodes | ||
pending_auto_registration | ||
pending_approval | ||
control_plane_ha_backoff_seconds | ||
data_plane_ha_enabled | ||
upgrading | ||
enable_radius_proxy |
aged_ar_penalty |
---|
id |
name |
amount |
days |
suspend_account |
note |
created_at |
updated_at |
created_by |
updated_by |
custom_email_id |
scratch |
record_type |
days_type |
Rotator
The rXg rotator service enables operators to simply and easily integrate content rotation into the captive portal web application. The system is designed to deliver zero-intervention advertising rotation via the captive portal web application to provide dynamic pre-authentication, post-authentication and interstitial advertising. In addition, the system can be used for a broad spectrum of other communication purposes other than advertising. For example, an operator may choose to use the rotator service to communicate late breaking news, integrate with third party messaging transport mechanisms or photographic galleries and real-time web cameras.
The rotator service may be directly accessed via an HTTP request to the rXg with a suffix of rotator
. The URN parameter must be specified to identify a particular rotator set that is to be accessed. Since the rotator service is accessible via a URL, it can be integrated into any third party display mechanism capable of making HTTP requests. For example, using a web browser connected to the LAN side of a newly installed rXg, open the URL:
https://rxg.local/rotator/?urn=postauth
.
The postauth
URN is a demonstration rotator that is part of the default rXg installation. It contains a series of advertisements that are displayed on the post-authentication landing page of the default portal. Reloading the web browser window will result in the rotation of the advertisements that are present in the chosen rotator.
The rotator service is implemented as a Ruby on Rails controller so that it may be easily integrated into the captive portal web application. Each time the captive portal page is loaded, the rotator displays a different payload.
To add a rotator to a captive portal page, edit the page and insert the following embedded ruby code where you would like the rotatee payload to be inserted:
<%= render partial: 'rotator', locals: { urn: ' **urn**' } %>
The urn
parameter in the example must be replaced with a string corresponding to a rotator scaffold entry. Incorrect specification of a rotator with a matching urn field will result in an error message being embedded into the portal page.
The rotator service is one of the many ways that the rXg enables operators to quickly and easily generate revenue from an end-user population. To maximize revenue, we strongly suggest that you partner with numerous affiliate programs that are appropriate to your end-user population. A good introductory text on affiliate programs is Make a Fortune Promoting Other People's Stuff Online: How Affiliate Marketing Can Make You Rich (ISBN 0071478132) by Rosalind Gardner. An excellent affiliate marketing recipe and ideas reference book is A Practical Guide to Affiliate Marketing: Quick Reference for Affiliate Managers & Merchants (ISBN 0979192706) by Evgenii Prussakov.
Rotators
An entry in the rotators scaffold creates a rotation group that can be integrated into the captive portal web application.
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 URN field configures the uniform resource name that uniquely identifies this rotator. The URN is the parameter that is used to choose a specific rotator when incorporating the rotator service into a captive portal page.
The rotatees list enables the operator to select rotatees from the set of all rotatees to associate with this rotator. The rotator will choose one rotatee to display from among the associated rotatees.
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.
Rotatees
An entry in the rotatees scaffold creates a member of a rotator group and specifies the payload that should be displayed.
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 rotator field defines one or more rotators for this rotatee to be associated with.
The payload field defines the data that will be presented when a rotator service associated with this rotatee is accessed. In a typical scenario, this field is populated with an HTML fragment that contains a block of text or a reference to an image that is part of an advertising campaign.
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.
Display and track advertisements
Navigate to Services::Ad Rotator.
The default portal by default looks for a Rotator with a URN of default to display the Rotatees. Create a new Rotator. The Name field is arrbitrary. Since the default portal looks for the URN of default set the URN field to default. Click Create.
Now that the Rotator has been configured, Rotatees can now be created that will contain the payload for the advertisement. In this example we will create Rotatees that will display on the main page of the default portal. Create a new Rotatee. The Name field is arrbitrary. In the Rotators field check the default box. The Payload field contains the url to the advertisement. The Target URL field contains the URL the user should be taken to if the click on the advertisement. The Price field is where the price paid for the advertisement can be entered and will be used in reports to calculate the price per impression/conversion. Do note that if the Payload is hosted outside the then it must be whitelisted on the splash portal in order for the content to be displayed. Click Create.
Repeat creating a Rotatee for each advertisement. In this example each advertisement is an image of fruit, and clicking on the advertisement image will link to wikipedia, but this could be the products homepage.
Rotator Logs will record an entry each time an Rotatee is loaded, it will display the IP of the device the advertisement was served to, along with the MAC address, Hostname, and Browser the device was using. The Rotator Logs will also show you if the advertisement was clicked.
The operator of the rXg can create reports showing detailed information about the number of clicks and conversions related to each Rotatee. To create a custom report navigate to Archives::Reports::Custom Reports.
There are two reports specific to the Ad Rotators. The first one is the Rotatee Metrics Custom Report. Create a new Custom Report. The Name field is arbitrary. Under Report set the Type field to Rotatee Metrics. Set the Time field to the desired time. Everyting else can be left to the defaults. Click Create.
The report can be viewed by clicking the view option on the left side of the scaffold. The Rotatee field shows the name of the Rotatee. The Impressions column displays the number of times the Rotatee was loaded and displayed. The Conversions column displays the number of times the Rotatee was clicked. The Conversion Ratio column displays the ratio of times Rotatee was loaded and clicked (Conversions divided by the number of Impressoins). The*Conversion Time(s)* section of the report gives you the average, minimum, and maximum number of conversions. Lastly the Cost section of the report displays the Price paid, the per impression cost (Price divided by the number of impressions), and the per conversion price (Price divided by the number of conversions).
The second report is the Rotator Impressions report. Create a new Custom Report. The Name field is arbitrary. Under Report set the Trype field to Rotator Impressions , and set the desired time for the report using the Time field. Click Create.
The report can be viewed by clicking the view option on the left side of the scaffold. The Impression column shows the date and time the Rotatee was displayed. The Rotator/Rotatee column shows which Rotatee the entry is for. The URL column shows the URL the device was trying to access when it was presented with the Rotatee. The IP field lists the IP of the device. The MAC field displays the MAC address of the device. The Hostname field will display the hostname of the device if available. The OS field displays the OS running on the device. The Browser field displays the browser the device is using along with the Version. The Login field displays the Policy the device is a member of. Lastly the Conversion Time(s) field displays the time between when the Rotatee was loaded and the user click on the Rotatee if applicable.
Display videos in captive portal based on location
In this example the rXg will be configured to display an advertisement video and static image in the captive portal based on the portal the device is accociated and the location of the device when it connects, using a prebuilt portal.
- Create Custom Portal.
- Create Splash and Landing portal to associate custom portal to.
- Create Shared Credential to activate ad rotator and allow access after advertisement.
- Create Rotators , this is what is used to determine which set of advertisements to display.
Create Rotatees , this is the advertisement content that will be displayed.
Create custom portal.
Navigate to System::Portals and create a new Custom Portal.
The Name field is arbitrary, for this example it will be named "videotest". The Controller name field is what is displayed in the URL when accessing the portal, for this example it will be "videotest". Set the Portal source field to Duplicate Local and the Duplicate field to default as the default portal will be used here. Click Create.
- Create Splash and Landing portal to associate custom portal to.
Navigate to Policies::Captive Portal and create a new Splash Portal.
The Name field is arbitrary, for this example it will be named "Splash". The rXg Portal field should be set to the portal created in step 1 which is "videotest". Select the policy associated unknown devices(devices connecting to the network for the first time), for the purpose of this example the "Onboarding Policy" will be selected. Click Create.
Create a new Landing Portal.
The Name field is arbitrary, for this example it will be named "Landing". The rXg Portal field should be set to the portal created in step 1 which is "videotest". Select the policy associated with devices that have authenticated for the purpose of this example the "Free Policy" will be selected. Click Create.
- Create Shared Credential to activate ad rotator and allow access after advertisement.
Navigate to Identities::Shared Credentials , and create a new Shared Credential Group.
The Name field is arbitrary, for this example it will be named "videotest". Remove the characters from the Credential field , the code is looking for a blank credential to activate the advertisements. The Policy field is used to select which policy the end user will become a member of after watching/viewing the advertisement, for this example the "Free" policy will be used. The Time field is used to set the amount of time the end user will be granted after authenicating, this will be set to 1 hour in this example. Both the Download quota and the Upload quota fields will be set to unlimited. By default a shared credential is valid for one week, this can be extended by changing the date in the Expires field, this will be set to the year 2099. Makes sure that the "Splash" portal is selected in the Splash Portals field. We can limit the number of simultaneous users by setting a value in the Simultaneous Users field, here it will be set to unlimited. If desired the Intersession field can be used to set a period of time that must pass before the same device can use the credential, this will be left at 0 for this example. Finally if we want to end user to be presented with the portal again if they leave the network and return we can uncheck the Automatic login checkbox. Click Create
- Create Rotators , this is what is used to determine which set of advertisements to display.
Navigate to Services::Ad Rotator. To determine which advertisements to display a Rotator must be created for each entity we want to match againts, a fallback can be created that will display advertisesments if there are no other matches. The URN for the fallback is the value "video", the rXg has the ability to match against the specific portal an end user is presented with, this can be further enhanced by adding a location as well. To start the fallback will be created first. Create a new Rotator.
Because this is the fallback enter "Fallback" in the Name field and the URN field value will be "video". Click Create.
The next Rotator will match against the portal created in Step 1. Create a new Rotator , for this example the value of the Name field will be "videotest" which matches the portal created earlier. Note: this name can be anything and does not need to match the portal name. The URN field will need to match the portal name as this Rotator will be used to match against the portal created in Step 1, the value for the URN field will be "videotest_video". Click Create.
This system is configured with Location Areas that consist of a Floor and two Regions we can match against. The floor is named "building1" and then there are two regions name "room1" and "room2" that can be used to match against. If the match is against "building1" then any device connected to an AP located within the regions attached to "building1" will display advertisements assigned to the Rotator. "Building1" contains the regions "room1" and "room2".
To match against "building1" create a new Rotator , the Name field is arbitrary for this the value will be set to Videotest_building1, and the URN value is "videotest_building1_video". Click Create.
To make the match specific to a region we can use the region name instead of "building1", create a new Rotator , the value for the Name field is arbitrary and will be set to "Videotest_room1" in this example. The URN field will be the portal we want to display this on followed by the region and then video, which results in "videotest_room1_video". Click Create.
- Create Rotatees , this is the advertisement content that will be displayed.
The final step is creating the entries that the rXg can draw from to display content. If more than one Rotatee is created per Rotator then the rXg will randomly pick a matching Rotatee. The default portal contains 3 images and 5 videos we can use to display for this example. To display one of the examples videos to an end user connected in room1 create a new Rotatee.
The Name field is arbitrary and its value will be set to "Video1" for this example. Select the "Videotest_room1" checkbox in the Rotators field to display this content to an end user connected in room1. For this example we will display a video of clouds in this Rotatee using the following Payload"<video class="w-100 mb-3" src="/static/portal/videotest/clouds_1.mp4" preload="none" muted webkit-playsinline playsinline style="display: none;">". Click Create This step can be repeated for each advertisement that should be displayed.
For the last example a Rotatee that contains a static image will be created to be displayed to end users as a fallback in the event they do not match aginst the portal or a location area. Create a new Rotatee. Provide a name and select the "Fallback" checkbox in the Rotators field. For this example we will use the payload "<img src="/static/portal/videotest/ad_one.png" width="80%" class="d-block mx-auto my-3">". Click Create. Note: for a list of images and videos provided in the default portal please scroll down.
The above examples were all locally hosted files within the /static directory of the captive portal. To use content that is stored remotely, a WAN target must be configued containing the domains and or IP addresses of where the content resides and it must be applied as a whitelist to the Splash portal. To create a WAN target navigate to Identities::Definitions and create a new WAN Target.
The Name field is arbitrary, value here will be "Ad Whitelist". In the Targets field enter the domains and or IP addresses that will contain content then click Create.
Once the WAN Target has been created, it must be set as a whitelist on the captive portal. Navigate to Policies::Captive Portal and edit the Splash portal.
Type the name of the WAN target into the Whitelist field and it will bring up any matching results, click on each one to add it to the whitelist. Click Update.
Now we can pull content from the domain(s) that are in the Whitelist. For example to pull content from rxg-lab.tech which is included in the Whitelist that was created. Create a new Rotatee give it a name, and the Payload will be <img src="https://rxg-lab.tech/images/ad\_two.png" width="80%" class="d-block mx-auto my-3">. Include the Rotators the content should be associated with and click Create. Note: to include external content it is important that you define a WAN target that contains all the domains and IP addresses content will be pulled from and this needs to be assigned to the Whitelist of the portal where the content will be displayed.
Static Image examples included in default portal.
- ad_one.png <img src="/static/portal/videotest/ad_one.png" width="80%" class="d-block mx-auto my-3">
- ad_two.png <img src="/static/portal/videotest/ad_two.png" width="80%" class="d-block mx-auto my-3">
- ad_three.png <img src="/static/portal/videotest/ad_three.png" width="80%" class="d-block mx-auto my-3">
Video examples included in default portal. 1. Big_Buck_Bunny_360_10s_1MB.mp4 <video class="w-100 mb-3" src="/static/portal/videotest/Big_Buck_Bunny_360_10s_1MB.mp4" preload="none" muted webkit-playsinline playsinline style="display: none;"> 2. clouds_1.mp4 <video class="w-100 mb-3" src="/static/portal/videotest/clouds_1.mp4" preload="none" muted webkit-playsinline playsinline style="display: none;"> 3. control_vid.mp4 <video class="w-100 mb-3" src="/static/portal/videotest/control_vid.mp4" preload="none" muted webkit-playsinline playsinline style="display: none;"> 4. money.mp4 <video class="w-100 mb-3" src="/static/portal/videotest/money.mp4" preload="none" muted webkit-playsinline playsinline style="display: none;"> 5. mountains_2.mp4 <video class="w-100 mb-3" src="/static/portal/videotest/mountains_2.mp4" preload="none" muted webkit-playsinline playsinline style="display: none;">
Note: The links provided above are linked to the custom portal created for the example, if you use these you may need to change the "videotest" portion of the link to match the name of the custom portal you created.
Advanced Servers
The servers view of the services menu displays scaffolds that allow the operator to customize the behavior of various services integrated into the rXg.
Remote Database Access
The local database of an rXg may be configured for read-only access by third-party software tools When an rXg is configured with local server database storage. The local server database storage methodology configures the rXg to utilize PostgreSQL as the on board database. PostgreSQL is an advanced open source relational database with a wide variety of access options supported by both community-based open source projects as well as proprietary commercial offerings. A quick search for PostgreSQL GUIreveals numerous possibilities.
Many of the tools that integrate with PostgreSQL have GUIs for exploration. In addition, the vast majority allow for arbitrary execution of SQL queries.
Remote access to the on board rXg database is used to accomplish a broad spectrum of tasks. Advanced and highly customized reporting is one common use case. Below is an example of a report generated by the pgAdmin PostgreSQL GUI tool for the login log.
Another common use for remote database access is for integration with a third-party accounting system. Below is a report generated by pgAdmin from the credit card transactions log. A third-party accounting package could be configured to retrieve all of the transactions recorded in a particular time for automatic posting and reconciliation.
The remote database access feature is also a very convenient way to take periodic backups of the rXg database. This may be accomplished via GUI tools, but is also very easy to script. For example, thepg_dump
utility may be run as a scheduled task on Windows or a cron job on a UNIX-based system to automate periodic backups of the rXg.
Remote database access is governed by the Database scaffold as discussed below. The default PostgreSQL port is used and the default database name is config
. The name of the database being used by the rXg may be changed via the Cluster view of the administrative console. It is strongly advised that the default database name be used.
Remote database access is a powerful tool for operators who wish to integrate the rXg with third-party devices, systems and software. Nearly any form of read-only integration may be achieved. To obtain read-write access to the database, the rXg API key mechanism (discussed in the Adminis view) must be used.
Database
Entries in the database scaffold define the remote access policy and credentials for the local database on an rXg. This scaffold is only accessible on an rXg that is configured to use a local server database storage type.
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 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.
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
The username and password fields contain the credentials for accessing the database. These credentials are generated by the rXg and are immutable.
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.
NTP Server
Entries in the NTP Server scaffold define configuration profiles for the rXg integrated NTP server. Precise and accurate local time keeping is a critical aspect of a functioning and error free billing system. The rXg uses the network time protocol to synchronize the local clock with established servers. In addition, both local and remote devices may be configured to use the rXg as a NTP server.
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 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.
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
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.
SNMP Server
Entries in the SNMP Server scaffold define configuration profiles for the rXg integrated SNMP server. Many of the instruments that may be accessed via the rXg administrative console are also available via SNMP. This allows the rXg to be probed by a SNMP network or element management system and enables the operator to use to integrate the rXg as part of a large scale heterogeneous network.
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 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 community is the read only (r/o) string that is used to gain access to this rXg via SNMP. Remote access to SNMP is disabled by default.
The port field specifies which port the SNMP server should listen for SNMP probes.
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
The Receive Traps option enables the SNMP Trap listener on the rXg. Access to the server is restricted by the visibility and WAN Target selections. SNMP agents may use the community string specified here or the community string of an Infrastructure Device.
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.
SNMP MIBs
Integrating any network device with an SNMP monitoring solution usually requires MIBs. The following is list of MIBs that are available to download to assist with SNMP integration to the rXg:
TFTP Server
Entries in the TFTP Server scaffold define configuration profiles for the rXg integrated TFTP server. May third-party networking devices are configured by loading files over TFTP. The intended use of the rXg integrated TFTP server is to simplify the process of configuring and configuring provisioning of third-party devices.
The TFTP server delivers files out of /space/tftpboot
. It is assumed that the operator will use SFTP to transfer files to the rXg that will be served by the rXg integrated TFTP server. In addition, the rXg captive portal may be customized to generate files into this directory for zero operator intervention provisioning scenarios. For example, the captive portal may be customized to generate files for provisioning VoIP ATAs and telephones for end-users who have purchased a usage plan that incorporates a VoIP package.
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 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 WAN targets and policies fields specify which sets of hosts should be allowed access to the rXg integrated TFTP server. TFTP does not include any authentication. Thus, by default, no access is allowed to the rXg integrated TFTP server. The operator must specifically enable access to hosts 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 which is selected here.
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.
Iperf Server
Entries in the Iperf Server scaffold define configuration profiles for the rXg integrated Iperf server. Iperf is the de-fato standard mechanism for measuring the available network bandwidth. To use this feature of the rXg, the operator must have an Iperf client installed on one or more external devices.
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 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 port field configures the port that the Iperf server will be listening for connections on. The default port is 5201.
The WAN targets and policies fields specify which sets of hosts should be allowed access to the rXg integrated Iperf server. Iperf does not include any authentication. Thus, by default, no access is allowed to the rXg integrated Iperf server. The operator must specifically enable access to hosts 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 which is selected here.
The rXg integrated Iperf server is most often used with devices on the LAN to instrument the maximum bandwidth between an end-user device and the rXg. The maximum speed reported by Iperf will be determined by the physical media speed and the bandwidth queue that is associated with the client device. Note that if the end-user has been associated with a usage quota, the use of Iperf will be counted into the quota.
Iperf may also be used from the WAN side to instrument the maximum bandwidth available on WAN uplinks. In order to acquire correct data, the Iperf client should be placed immediately adjacent to the rXg on the WAN. Using a Iperf client that is multiple hops away from the rXg will usually provide nonsensical results because it is impossible to guarantee that the intermediate hops will have sufficient bandwidth for the test.
The use of Iperf is highly preferred to web-based online bandwidth meters such as speedtest.net. This is because the Iperf server enables the operator to independently test the LAN distribution network and the WAN uplinks. A web-based online bandwidth meter can only perform a complete end-to-end test that does not provide any information as to where the potential problem is. Also, the results from an web-based online bandwidth meter test may be skewed by proxies, including the rXg integrated transparent web proxy.
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.
MQTT Server
Entries in the MQTT Server scaffold define configuration profiles for the rXg integrated MQTT server.
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 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 WAN targets and policies fields specify which sets of hosts should be allowed access to the rXg integrated MQTT server. MQTT does not include any authentication. Thus, by default, no access is allowed to the rXg integrated MQTT server. The operator must specifically enable access to hosts 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 which is selected here.
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.
Virtualization
- Virtualization Deployment Guide
- Virtualization Design Guide
The virtualization view presents the scaffolds associated with configuring a virtual environment, including hosts, guests, and networking.
Virtualization Deployment Guide
The most common use case of virtualization within the rXg is to cluster multiple rXgs together on the same bare metal machine to maximize the use of available resources. The following steps will guide you through building a virtual infrastructure capable of clustering.
Note: If rXg virtualization host is itself installed onto a virtual machine running on ESXi, ensure that hardware virtualization is enabled in the VM options.
Create a Virtualization Host
From the Virtualization Hosts scaffold, click Create New
A host can be created on any bare metal node you wish to use as a virtualization environment. Assign the host a name and select the node that will be used for virtualization. The Autostart delay can be left at the default of 5 seconds. You will notice that a virtual switch has already been added for each physical interface on the host. Keep this configuration as is; at the bottom, you can click create.
Note: It is necessary to have the physical interface for the cluster network in an active state, even if there is no plan to egress traffic from that interface.
Load the ISO onto the Host
Once the host is created, you can click Disk Images to load the ISO file that will be used as the operating system for your virtual machines.
Next, click Create New.
The Filename field is required. This will be used to reference the associated .iso file. The rXg provides two methods to load the .iso file onto the system. You can provide a URL that points to the .iso file, and the rXg will download it directly, or you can use the File Upload method to select an .iso from your local machine to upload to the system.
Once the upload/download is complete, you will see the file in the list.
Create a Virtual Machine
From the Virtualization Machines scaffold, click Create New
Assign the virtual machine a name and select the host that it should be built on.
Cluster Node Auto Provision
If this VM is to be part of a cluster, and the Virtualization Host is the CC, you can use the Cluster Node dropdown to automate the clustering configuration. The rXg will combine the data collected from this form with available information from the CC, create a configuration template, and automatically apply it after the software installation is complete. This process allows the VM to join the cluster automatically.
Note: The host CC record (System >> Cluster) will need to be configured for Automatic Registration.
The Cluster Node dropdown will allow you to select an existing cluster node record or create a new one. If you choose an existing record, you need to check the Auto Provision option to activate this feature. All other required information is collected from the current configuration. If you choose Create New, providing the Node Mode and Node IP address will also be necessary.
Create New
Existing Record
The bootloader can stay at the default setting for the rXg installation. Other operating systems, such as Windows, may require a different bootloader. Set the memory and CPU count as necessary to support the VM that you are creating. It is recommended to enable Autostart so that if the host is power cycled, the guest VM will automatically start back up. Add virtual interfaces as needed and assign them to a virtual switch. In this example, I have created a virtual interface for the WAN, CIN, and LAN and matched them to the physical ports I plan to use on the host. Add a virtual disk to the VM of the appropriate size to support the rXg that you are installing. Adding an additional 20 GB of space is necessary to allow for overhead here. Click Create.
Begin the OS Installation
With the VM created, you can click the Install link to select a disk image for installation.
Select the desired image and click Install.
Console Access
The console can be reached via an SSH session to the host node and then switching to the root user.
Type vm console your_vm_name
.
Press Enter
To exit the console session, assuming you were SSH'd to the host, type "~~."
You may need to press enter before the first ~ if it doesn't work the first time. (needs to be entered on its own input line)
After installation, the node can be configured from the primary CC.
Virtualization Hosts
The Virtualization Hosts scaffold enables creation, modification, and deletion of a host. The first step to creating a virtual machine in rXg is creating a virtualization host.
The Name field is an arbitrary string used to identify the host. This string is used for identification purposes only.
A virtualization host can be created on any of the bare metal machines in a cluster. The Node dropdown allows you to select the intended target for this configuration.
The Autostart Delay field defines the number of seconds to wait between starting each virtual machine with autostart enabled.
The Virtual Switches field allows for the creation of vswitches that virtual ports can later be attached to. One virtual switch per host interface will automatically be created when you create a new host.
The Virtual Machines field displays all virtual machines that are either unassigned (unchecked) or assigned (checked) to this host.
The Disk Images link, when selected, will allow the operator to manage the .iso files stored for virtual machine creation. Create New will provide the operator with options to either upload or download a new .iso file. The Filename field is required and will be used to reference the associated .iso file. The rXg can directly download a .iso file from a remote destination specified in the URL field. Alternatively, you can select Choose File and select a .iso file from your local machine for upload.
Virtual Machines
The Virtual Machines scaffold enables creation, modification, and deletion of virtual machines.
The Name field is an arbitrary string used to identify the host. This string is used for identification purposes only.
The Host dropdown allows you to specify the host for the virtual machine creation.
If this VM is to be part of a cluster, and the Virtualization Host is the CC, you can use the Cluster Node dropdown to automate the clustering configuration. The rXg will combine the data collected from this form with available information from the CC, create a configuration template, and automatically apply it after the software installation is complete. This process allows the VM to join the cluster automatically. The cluster node dropdown will allow you to select an existing cluster node record or create a new one. If you choose an existing record, you need to check the Auto Provision option to activate this feature. All other required information is collected from the current configuration. If you choose Create New , providing the Node Mode and Node IP address will also be necessary.
The Bootloader field allows for selecting a specific set of booting instructions that is most appropriate for your virtual machine. Use Bhyveload for rXg.
The Memory field allows the number of gigabytes of memory that should be allocated from the host to the virtual machine to be specified.
The Cores field allows the number of CPU cores that should be allocated from the host to the virtual machine to be specified.
The Autostart checkbox, if checked, will automatically start the virtual machine when the host starts. A delay between virtual machine starts can be configured in the host scaffold.
The Enable Graphics field, if selected, will start a VNC server to provide GUI access to the VM.
The Virtual interfaces section allows for the creation of virtual interfaces that can connect the virtual machine to the virtual switch. Creating a virtual interface in this scaffold will also add it to the Virtual Interfaces scaffold. The name field is an arbitrary string used to identify the interface. This string is used for identification purposes only. The emulation field allows for the specification of the emulation type. Virtio-net is recommended in most cases. The virtual switch dropdown allows you to select with which switch the interface you are creating will be assigned. A virtual switch enables interfaces to communicate with each other or with an associated uplink. The MAC field allows the assignment of a custom MAC address to the interface. Leaving this field blank will result in a MAC address being automatically created.
The Virtual disks section allows for creating a virtual drive that can connect to this virtual machine. Creating a virtual disk in this scaffold will also add it to the Virtual Disks scaffold. The name field is an arbitrary string used to identify the interface. This string is used for identification purposes only. The Size field specifies the number of gigabytes of drive space that should be allocated from the host to the virtual machine. The emulation field allows for the specification of the emulation type. Virtio-blk is recommended in most cases.
Virtual Switches
The Virtual Switches scaffold enables the creation, modification, and deletion of virtual switches.
The Name field is an arbitrary string used to identify the host. This string is used for identification purposes only.
The Host dropdown allows you to specify the host for the virtual switch creation.
The Switch Type dropdown allows a switch type to be specified. Standard is recommended for most cases.
The Interface dropdown provides a list of available physical interfaces from the host machine. Selecting an interface from this dropdown will assign it to this virtual switch as an uplink. Each physical interface can only be assigned to one virtual switch.
The Virtual Interfaces field provides a list of available virtual interfaces that can be assigned to this switch. Selecting an interface from this dropdown will assign it to this virtual switch and unassign it from any other switch.
Virtual Disks
The Virtual Disks scaffold enables the creation, modification, and deletion of virtual disks.
The Name field is an arbitrary string used to identify the host. This string is used for identification purposes only.
The Virtual Machine dropdown specifies with which virtual machine this disk should be associated.
The Size (GB) field specifies the number of gigabytes of drive space that should be allocated from the host to the virtual machine.
The emulation field allows for the specification of the emulation type. Virtio-blk is recommended in most cases.
Virtual Interfaces
The Virtual Interfaces scaffold enables the creation, modification, and deletion of virtual interfaces.
The Name field is an arbitrary string used to identify the host. This string is used for identification purposes only.
The Virtual Machine dropdown allows you to select with which virtual machine the interface you are creating will be assigned.
The Virtual Switch dropdown allows you to select with which switch the interface you are creating will be assigned. A virtual switch enables interfaces to communicate with each other or with an associated uplink.
The Emulation field allows for the specification of the emulation type. Virtio-net is recommended in most cases.
The MAC field allows the assignment of a custom MAC address to the interface. Leaving this field blank will result in a MAC address being automatically created.
Virtualization Design Guide
Note: We recommend that a single machine with a single instance of rXg be limited to 1500 DPL, 8 CPU cores, and 16 GB of RAM.
No HA Required
- Single rXg Host Internal Dataplane Virtualization
HA Required
- 2-way Symmetric rXg Cluster
- 3-way Symmetric rXg Cluster
- 3-way Asymmetric rXg Cluster
- 4-way Asymmetric rXg Cluster
- 8-way Asymmetric rXg Cluster
Single rXg Host Internal Dataplane Virtualization
- Install rXg on bare metal machine
- Configure bare metal rXg as CC
- Also use the bare metal rXg as virtualization host
- Install (6) vDPs
- Configure bare metal rXg as CC
Example:
- Server with AMD 64-core CPU / 256 GB of RAM
- 6-way IDV (8 cores / 16 GB each)
- 16 cores and 64GB RAM for CC
- 6000 DPL in full operation
2-way Symmetric rXg Cluster
- Install rXg on both bare metal machines.
- Configure bare metal rXgs as symmetric rXg cluster with (2) CCs
- Also use the bare metal rXgs as virtualization hosts
- Install (2) vDPs per node
- Use cluster teaming to facilitate deterministic failover
- Configure bare metal rXgs as symmetric rXg cluster with (2) CCs
Example:
- 2 x servers with AMD 24-core CPU / 64 GB of RAM
- 2-way IDV (8 cores / 16 GB each) on each server
- 8 cores and 32GB RAM for CC
- 4000 DPL in full operation (2000 DPL if one fails)
3-way Symmetric rXg Cluster
- Install rXg on all 3 bare metal machines.
- Configure bare metal rXgs as symmetric rXg cluster with (3) CCs
- Also use the bare metal rXgs as virtualization hosts
- Install (4) vDPs per node
- Use cluster teaming to facilitate deterministic failover
- Configure bare metal rXgs as symmetric rXg cluster with (3) CCs
Example:
- 3 x servers with AMD 48-core CPU / 128 GB of RAM
- 4-way IDV on each server
- 16 cores and 64 GB RAM for CC
- 12000 DPL in full operation (8000 DPL if one fails)
3-way Asymmetric rXg Cluster
- Install rXg on all 3 bare metal machines.
- Configure bare metal rXgs as asymmetric rXg cluster with (1) CC and (2) DPs
- Use the bare metal DP nodes as virtualization hosts
- Install (4) vDPs per DP node
- Configure bare metal rXgs as asymmetric rXg cluster with (1) CC and (2) DPs
Example:
- 3 x servers with AMD 32-core CPU / 64 GB of RAM
- rXg CC runs on bare metal
- 4-way IDV on bare metal rXg DPs
- 16 cores and 40 GB RAM for CC
- 16 cores and 24 GB RAM for VMs - 8000 DPL in full operation (4000 DPL if one fails)
6-way Asymmetric rXg Cluster
- Install rXg on all 4 bare metal machines.
- Configure bare metal rXgs as asymmetric rXg cluster with (2) CCs and (2) DPs
- Use the bare metal DP nodes as virtualization hosts
- Install (4) vDPs per DP node
- Use cluster teaming to facilitate deterministic failover
- Configure bare metal rXgs as asymmetric rXg cluster with (2) CCs and (2) DPs
Example:
- 6 x servers with AMD 32-core CPU / 64 GB of RAM
- 4-way IDV (8 cores / 16 GB each) on each vDP
- Full capacity of bare metal for master and standby CC
- 16000 DPL in full operation (12000 DPL if one CP or DP or both fails)
8-way Asymmetric rXg Cluster
- Install rXg on all 8 bare metal machines.
- Configure bare metal rXgs as asymmetric rXg cluster with (2) CCs and (6) DPs
- Use the bare metal DP nodes as virtualization hosts
- Install (16) vDPs per DP node
- Use cluster teaming to facilitate deterministic failover
- Configure bare metal rXgs as asymmetric rXg cluster with (2) CCs and (6) DPs
Example:
- 8 x servers with 2x AMD 64-core CPU / 512 GB of RAM
- 16-way IDV (8 cores / 16 GB each) on each vDP
- Full capacity of bare metal for master and standby CC
- 96,000 DPL in full operation with room to grow!
LLM
The LLM view enables the operator to configure a cutting-edge retrieval augmented generation (RAG) large language model (LLM) artificially intelligent (AI) feature designed to empower network operators to harness the power of advanced language models within their private networks. By leveraging this innovative technology, operators can revolutionize network operations, enhance customer experiences, and unlock new revenue streams.
LLM Options
The LLM Options scaffold configures the end-user behavior of the LLM feature. It may be useful to think of each LLM Option as a unique chatbot. In a scenario where there are multiple end-user and operator portals, multiple LLM Option records may be created to drive each portal to a unique chatbot experience.
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 default checkbox, if checked specifies this LLM Option will be used for all portals without an explicit LLM option defined.
The temperature field is a number between 0 and 1 (0.8 default). Increasing the temperature value will make the model answer more creatively.
The chatbot name field is used to set the name of the chatbot, default is Romeo George.
The chatbot avatar field allows the operator to upload a custom image to be as the chatbots avatar in chatbox window.
The apply guardrails checkbox applies guardrails against harmful, unethical, racist, sexist, toxic, etc. conversations. This is applied after any custom instructions and is enabled by default.
The custom instructions field allows the operator to provide the LLM with a full set of custom system instructions.
The initial greeting field allows the operator to specify a specific greeting the chatbox will use to introduce itself when a user initiates a new chat.
The default llm model drop down is used to specify the default LLM modem this LLM will use.
The llm models field allows the operator to select all the models that can be used with this LLM Option.
The admin roles field sets the admin roles that will use this LLM option, selecting any roles here will remove them from being selected in another LLM option.
The operator portal field selects which Operator Portals are assigned to this LLM Option. Note that an admin role match is prioritized over an operator portal match. Associating a record removes it from other options.
The landing portals field sets which splash/landing portals use this LLM option. Associating a record removes it from the other options.
The alow anonymous chats field, if checked allows users to chat via the portal without being logged in with an account.
LLM Workers
The LLM Workers scaffold configures an LLM back-end service that will be used by the chatbots defined by LLM Options. LLM Workers may leverage both local as well as remote GPU resources. The remote GPU resource configuration is intended to be used with a Fleet Manager. An organization might wish to install one or more GPUs into the Fleet Manager and thus have a centralized pool of GPU resources that are shared amongst of a fleet in order to meet cost, power, and cooling budgets at the edge. It is also possible to create LLM Workers that leverage cloud AI systems. We highly recommend that operators deploy their own GPUs to maximize ROI and information security. Tying an LLM Worker to a cloud system is primarily included for the purpose of demonstration.
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 adapter field specifies the adapter to be used, Ollama is selected by default.
The run locally checkbox tells the system to run a local server for the specfied backend (adapter) and optionally can be made available to specific WAN targets and or policies.
The host field is used to specify the IP or FQDN of the host providing the API interface for the designated backend.
The port field specifies the port to be used for communication.
The timeout field sets the amount of time the system should wait for the LLM worker to respond.
The online checkbox, if checked indicates that the LLM worker is online and ready to process reqquests, unchecking this field will make the LLM worker unavailable.
The llm model drop down specifies which LLM Model this worker will use by default.
The llm models field specfies which LLM Models this worker is allowed to use.
The use for embeddings field if checked, designates the worker that will be used to generate embeddings for context lookup. Enabling will deactive embedding for other workers.
LLM Models
The LLM Models scaffold displays the models that are available to the LLM Worker. Use the import models action link on the LLM Worker to bring in the available models and populate this scaffold. This scaffold is primarily for informational purposes. We recommend pulling llama3.1:latest for most purposes, or llama3.1:70b if you have more than 40 GB of VRAM. We recommend pulling nomic-embed-text (or mxbai-embed-large if you have a powerful machine) for embeddings.
The name field is the name of the model as recognized by the LLM Workers running it. This name needs to match the model name this field is not arbitrary.
The url NEED Clarification here, does it pull the model to the system and the URL is where that model can be downloaded from.
The formatter specifies which LLM model to use to format the requests that are sent to the LLM Worker Needs clarification
The context window sets the size of the set of information that is relevant for answering questions. Setting a larger context window can allow for more detailed and comprehensive answers. What limits this
The embedding dimensions field sets the scope for how many different features/variables are being considered, different models require varying amounts of data.
The quantization level field is used to set how many bits are being used per word when encoding text data. The higher this value the more detail can be gained from the information/data.
LLM Sources
The LLM Sources scaffold allows operators to upload data sources that are used by the retrieval augmented generation (RAG) system. Documents uploaded to this scaffold are indexed using an embeddings model. Vector similarity search is performed upon the chatbot input to acquire relevant fragments of LLM Sources to provide context to the LLM when generating a chatbot response.
The intended method of use is for the operator to upload a large number of files from their existing dataset. For example, the operator might upload all of the menus for all of the restaurants at a large public venue. Another common use case would be an upload of all of the recommended nearby activities for a hospitality venue. The LLM Sources are unique to each edge. Synchronization of LLM Sources between edges is accomplished using a Fleet Manager.
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 llm_remote_data_source if selected, marks this LLM Source as remote, meaning that the rXg is expected to fetch the source data from a remote host.
The frequency selector allows the operator to choose whether to make the llm source get called live, or periodically. If it is called periodically, it will not have access to a specific user's specific query, the way it will if being called live. If this LLM Option is periodic, the remote source will be called periodically and the result will be stored in the LLM Option's source attachment, and a button to manually refresh it will be made available. If this is a Live LLM Source, the query will be accessible from within the parameterization's ERB context as the query variable.
The source field lets you choose the file to upload that will be used as an embeded source.
The visibilty field sets which users can access this information, if set to admins only, the source will only be referenced if you are logged in as an admin. Admins and Users allows both admins and client users to receieve information from this source, and setting it to anonymous allows any user interacting with the LLM to recieve this information regardless of being logged in or not. The anonymous setting should only be used if the client would be interacting with the chatbot without a login sessions, ie from the splash portal.
The request properties are merged with the request properties of the remote llm data source when this data is retreived.
These request properties can use ERB, and if they do, the user's query will be available in that ERB context as the query
variable. Other variables such as client_ip
, client_mac
, current_account_id
, anonymous_user_id
, connected_ap_id
, current_admin_id
will be available if possible.
The path attribute is merged with the base url of the LLM Remote Data Source to determine the URI that will be called. This allows the operator to configure different paths with different query parameters off of one LLM Remote Data Source.
The timeout attribute determines how long the rXg will wait for a response when it tries to query the remote data source.
The frequency field choice determines how often a periodic remote data source is redownloaded.
The cache duration field determines how long an on-demand response is cached for. This works in conjunction with the cache duration unit field.
LLM Remote Data Sources
LLM Remote Data Sources Represent "base" configuration for getting data from remote web servers to use in LLM generated responses. LLM Remote Data Sources contain properties that are used when requesting data from that remote llm source.
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 base url field will be combined with the path attribute of a correlated LLM Source. This is intended to give operators significant flexibility when using LLM Remote Data Sources.
The request properties will be merged with the LLM Source's request properties when making the request.
These request properties can use ERB, and if they do, the user's query will be available in that ERB context as the query
variable. Other variables such as client_ip
, client_mac
, current_account_id
, anonymous_user_id
, connected_ap_id
, current_admin_id
will be available if possible.
The basic auth username and basic auth password will be included as basic auth if they are present.
LLM Embeddings
The LLM Embeddings scaffold displays all of the indexes that have been created by the embeddings model for the various LLM Sources. This scaffold is intended for informational purposes only.
An entry in the embedding scaffold represents data the LLM can pull from to answer client questions. The source shows where the data is from, updated reflects the last time this information was updated, the llm model used and the dimensionality.
LLM Prompts
This scaffold is a list of all the prompts sent to the LLM from the clients.
LLM Requests
This scaffold is a list of all the prompts sent to the LLM from the clients, it will list which llm model was used, the LLM worker, when the task was started, when it completed, and how long it took to complete the response.
Chats
The chats scaffold is a history of the chats that have been initiated on the system.
LLM Setup Example
In this example the hardware is a pc with a 3090 graphics card, WAN + certificate is configured, no other configuration has been done.
Navigate to Services::LLM
Create a new LLM Worker.
Give the record a name, in this case since it will be running locally on the system using Ollama I will use the name Local Ollama.
The adapter field should be set to Ollama, and the run locally checkbox should be checked.
The default port value of 11434 should be used, and timeout can be left at 30 seconds. It may be necessary to increase the timeout to 120 seconds to support larger models such as the 70b variant of llama.
Add any WAN targets that should be allowed to communicate on this port and/or any polcies that should be allowed. Being that there is no other configuration currently on this system I will select the default policy, if this were a live deployment I would need to add any client policies that will have access to the chatbot.
Leave the online checkbox, checked.
We do not have any llm models yet so we will leave those fields blank. In this demo we will also be using this worker for the embedding so the use for embeddings checkbox should be checked.
Click Create.
To pull a new model click the pull model link and enter the name of the model to be fetched.
Here we will pull the latest llama3 model, then click submit. This process can take a long time to complete as it must download and process the model file which an be quite large. If the model does not automatically appear in the model scaffold after pulling, wait a bit longer, and click the Import models link in the scaffold.
Repeat for each desired model.
Edit the LLM Worker created previously and now we can select the default model to use with this worker as well as specify other models the worker can use.
After selecting the default LLM model and any additional models click create.
Next we will enable embedding generation. Embeddings are numerical representations of text or other data, which can be compared against each other in order to detect similarity between different data. If enabled, embeddings will be created for the Retrieval Augmented Generation (RAG) sources, as well as the admin manual and the Active Record Models that make up the database. There must be a worker designated for creating embeddings as well as a model designated for embeddings. For this we will use the nomic-embed-text:latest model. Edit the nomic LLM worker.
The embedding dimensions field is required when using a model for embedding. This field is typically populated automatically when importing models from a worker. Valid values are as follows: 512, 768, 1024. Default is 768 and will be used if the field is blank. Check the use for embeddings checkbox and click update. NOTE It will not start generating LLM embeddings until we create the LLM Option which brings us to the next step.
Create a new LLM Option.
Give the record a name, since this will be the default LLM Option I will call it default, and check the default box below the name field. If desired you can enter a name for the chatbot, and upload a custom avatar.
Be default apply guardrails is checked, for the purpose of this demo it will remain checked.
I will not be changing the custom instructions or the the initial greeting at this time.
Select the default LLM model, for this we will be using llama3:latest, I will select the other models as well.
In the Provisioning section select which admin roles that will use this option set. If there are any operator portals or splash/landing portals that should use this LLM option they can be selected at this time as well. If the goal is to allow anyone to access the chatbot without a login session check allow anonymous chats. Primarily this would be checked if you intend to have the chatbot on the splash portal before authentication.
Click create.
This will then start generating the LLM Embeddings to be used as resources for chat responses. The time it will take to generate the embeddings depends on hardware.
The Chat is now available for use in the admin gui.
LLM Remote Sources Example
Using the LLM Remote Data Source feature allows the system to pull in realtime data via API calls. In this example we will create a remote data source that pulls information from Aviationstack.com. In this example we are using the paid service, however I believe a free account allows 100 API calls per month.
Before we begin we should determine which API endpoints we will use. We can see a list of available API calls for Aviationstack here aviationstack.com/documentation. For this example we will using the following endpoints.
dep_iata which allows us to narrow the scope of our searches to a specific airport.
flight_date which allows us to specify a time for our queries.
flight_number which allows us to inquire about specific flights.
Lastly access_key which is required and will pass our API access key.
To begin using Remote Data Sources navigate to Services::LLM and create a new LLM Remote Data Source.
Give the record a name. Enter the base URL, which for aviationstack is https://api.aviationstack.com/. Next we need to configure a Request property. Kind should be set to Query Parameter, key set to access_key from the endpoint above, and the value is the API key provided by aviationstack. Click Create.
Next create a new LLM Source.
Give the record a name. Set the Visibility field to Admins and users, if we leave it at the defult Admins, then only admins will be able to access this source, we want clients on the network that have logged in to be able to access this. Setting it to anonymous then a client would be able to access the source regardless of login status.
The path here needs to be set to v1/flights for aviationstack. Select the LLM Remote Data Source that we created previously in the LLM remote data source field.
The Remote Data Description field is important and we must provide a value here. This is what the system will look at to determine if this source has information relevant to the inquery.
Next we need to create the Request Properties to use for this source. We will be using dep_iata to narrow the scope to a specific airport in this example DEN (Denver), flight_date which allows to search for a specific dates/times, and finally flight_number which allows us to retrieve information based on the specific flight numbers.
Click Create.
Now we should see a new LLM Embedding for this source, if not, click the Regenerate Embeddings link above the LLM Embeddings.
Now we are ready to start asking questions.
GPUs
Nvidia datacenter and workstation GPUs are preferred. The RTX 4000 is the preferred GPU for space and power constrained scenarios. The RTX 4000 consumes a single PCI-e slot and contains 16 GB to 20 GB of VRAM which is enough to run most typical models. Production servers from major manufacturers are usually ordered with the Nvidia L40S GPU which comes with 48 GB of VRAM.
It is possible to use desktop GPUs which are often available a lower prices, especially in the second-hand market, which is useful for demonstation and development purposes. The Nvidia 3090 GPU is known to work and available at reasonable prices. The 24 GB of RAM present onboard the 3090 is to run most models. The 3090 GPU is also available in two-slot configurations. Later generation Nvidia GPUs such as the 4090 typically require three slots and provide similar amounts of VRAM.
It is possible to put two (or more) GPUs in the same machine. For example, two 3090s with 24 GB of VRAM, or three A4000s with 16 GB of VRAM each, would be enough to run Llama 3.1 70b which requires 40 GB of VRAM.
DHCP
The DHCP view presents the scaffolds associated with configuring the DHCP server and DHCP relay features of the rXg.
The rXg integrates a fully featured DHCP server capable of meeting the needs of nearly any imaginable environment. By default, the rXg DHCP server responds to all DHCP requests on the LAN with a temporary address assignment from within a pool. This behavior may be modified and augmented via the scaffolds presented on this view to deliver a broad spectrum of possible responses.
To enable the rXg integrated DHCP server, the operator must create a DHCP pool that falls within the CIDR of an address that is on the LAN of the rXg. An address is considered to be on the LAN of the rXg if the address is associated with an Ethernet interface , VLAN or is the destination in a static route.
The CIDR of the address from which the pool draws IP addresses from automatically determines the DHCP server listening interface as well as the subnet mask and default route that is presented to the client.
For example, given an rXg that has the following addresses :
- Ethernet Interface en1: 192.168.5.1 / 24
- VLAN 3800: 172.16.16.1 / 22 If a DHCP pool for with a range of 192.168.5.100 to 192.168.5.200 is created, the rXg integrated DHCP server will listen on en1 for DHCP requests in the native VLAN and respond with:
- IP address in range 192.168.5.100 to 192.168.5.200
- subnet mask 255.255.255.0
- default gateway 192.168.5.1 Similarly, if a pool with a range of 172.16.23.1 to 172.16.28.255 is created, then DHCP requests present on VLAN 3800 will see a response of:
- IP address in range 172.16.23.1 to 172.16.28.255
- subnet mask 255.255.240.0
- default gateway 172.16.16.1
Many networks combine DHCP assigned addresses with manually assigned static addresses. Use the pools scaffold to control the range of addresses issued by the rXg. It is extremely important to ensure that network administrators manually configure statically assigned addresses correctly to prevent overlap. It is also suggested that VLANs be used for L2 segregation of machines with statically assigned addresses from those pulling from DHCP in order to prevent IP address collisions. Alternatively, the network operator may choose to use DHCP fixed hosts in lieu of statically assigned addresses to achieve the same goal.
In most networks, there are some devices which should obtain the same IP address every time a request is made. A common occurrence of this is when a Static IP has been configured for a device that is using DHCP. To ensure connectivity, the BiNAT'ed device must have a static IP address or must be established as a fixed host. It is important to make sure that fixed hosts are assigned IP addresses that are outside of the ranges specified by the pools
Two, non-overlapping pools may also be configured for the same Ethernet interface or VLAN. Given the example rXg network address configuration above, 172.16.23.1 to 172.16.28.1 and 172.16.20.1 to 172.16.22.255 may both be configured as pools simultaneously. By default, requests originating from VLAN 3800 will draw addresses from both pools. This behavior is usually modified through the use of classes and match rules.
Match rules may be used to differentiate between requests originating from the same physical or logical media. For example, match rules may be used to associate devices presenting DHCP client identifiers containing a specific prefix with a class. Another common use of match rules is to place all devices presenting a MAC address from a specific vendor into a class.
A class may be used to determine the pool from which the requesting device acquires an address. This is useful for IP-based policy management as certain devices may be placed into specific ranges of IP addresses which can have different policies associated with them. In addition, different pools may have different DHCP options. For example, pools may have different maximum lease times, DNS servers, default routes, etc.
If there is a LAN CIDR block configured on the rXg for which there is no pool , the rXg may also be configured as a DHCP relay server. This feature enables a DHCP proxy server on the rXg that forwards DHCP requests originating from the associated Ethernet interface or VLAN to an external DHCP server.
Pools
An entry in the DHCP Pools scaffold configures a pool of IP addresses that are to be offered to end-user devices requesting an IP address.
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 start IP and end IP fields define the range of addresses to be offered by this pool. The pool of offered addresses must fall within the range of an IP network configured on an interface and must not include the address(es) consumed by the rXg or the broadcast address. For example, if the 192.168.5.1/24 IP network is configured on the LAN, the maximum allowable range is from the start IP of 192.168.5.2 to the end IP of 192.168.5.254.
It is critically important to be very precise when entering these values to prevent IP address conflicts. Some of the many things to keep in mind include:
- Devices with statically assigned IP addresses must not use addresses within the DHCP pool range.
- IP address reservations (specified in the fixed hosts scaffold) must not be in the pool.
- The pool ranges must be large enough to accommodate the end-user population.
The Reserved options let you specify addresses you wish to reserve either at the begining of each subnet in the pool via the First field or at the end of the subnet via the Last field. For example a network address consisting of 32 /24 subnets (x.x.0.1/24 - x.x.31.1/24 (32)) setting the First field to 4 would reserve x.x.0.2 - x.x.0.5 in the first subnet and .2 - .5 in each subsequent subnet. Setting the Last field to 4 would reserve x.x.0.251 - x.x.0.254 in the first subnet and 251 - 254 in each subsequent subnet. The Router field can change the gateway IP in each subnet. Incremented from the network address, where 1 is the first usable IP address (e.g. x.x.x.1/24). Decremented from the last usable address, where -1 means the last host address (e.g. x.x.x.254/24).
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 option group and class fields link this DHCP pool with options and configuration rules. For example, the WINS server DHCP option can be transmitted to only those end-users running Window through the use of the option group and class fields.
Fixed Hosts
An entry in the Fixed Hosts scaffold reserves an IP address for a particular device. When a device with the MAC address specified in this record requests network configuration via DHCP, the specified IP address is offered. This mechanism is often used as an alternative to manually assigning static IP addresses to devices.
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 IP field contains the IP address to be reserved for this device. It is critically important that the reserved IP be outside of any pools specified in the pools scaffold.
The MAC field contains the MAC address of the device that this reservation is being held for.
The hostname field is an optional parameter that, if specified, will cause the DHCP server to deliver a client identifier to the device via a DHCP option.
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 option group links this reservation with a set of DHCP options that control additional information that may be delivered to the device beyond IP address, hostname, subnet mask and gateway. For example, an option group may be used to specify alternative DNS servers for the device specified in this reservation.
Option Groups
An entry in the option groups scaffold links one or more options to devices that are offered addresses from a pool or set of fixed hosts. When an option is linked, the specified payload will be delivered as part of the DHCP response offered to a requesting device. The use of option groups to link options to pools and fixed hosts maximizes the flexible reuse of configuration options.
The global check box links the associated options with all DHCP responses. Only a single option group can have the global field checked. Furthermore, the global checkbox should be used in exclusion to linking any specific pools and fixed hosts and vice versa.
The authoritative check box indicates whether or not the DHCP server should be authoritative for the network(s) its attached to. An authoritative DHCP server will assume that the configuration information about a given network segment is known to be correct and authoritative, and thus will send DHCPNAK messages to misconfigured clients. Operators setting up DHCP servers for their networks should usually have this checked to indicate that the DHCP server should send DHCPNAK messages to misconfigured clients. If this is not done, clients will be unable to get a correct IP address after changing subnets until their old lease has expired, which could take quite a long time. For certain cluster deployment configurations it is necessary to put the server in non authoritative mode. For example, when two or more cluster nodes are performing the role of the DHCP server on the same network. This is so that the nodes do not NAK each others lease assignments.
The BOOTP check box allows or denies address assignment from the related pool(s) for BOOTP clients.
The options field specifies the members of the options scaffold that will be linked to the targets specified in this option groups record.
The pools and fixed hosts fields specify targets for receiving the DHCP configuration options specified by the options fields.
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.
Options
An entry in the options scaffold establishes a key-value pair that can be appended to any DHCP response via an option group.
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 standard option field specifies the DHCP option that is to be defined by this record. The purpose of the vast majority of the DHCP options is easily derived by the name. The set of all available standard DHCP options is defined by IETF RFC 2132. The custom option field enables the operator to deploy DHCP options that are not part of IETF RFC 2132.
The name makes the purpose of the option self evident in many cases. Here are some common required use cases:
routersWhen the rXg integrated DHCP server is responding to requests originating from a network that is L2 connected to the rXg, the DHCP server automatically populates the response with a next hop router specified as the rXg. However, if the rXg integrated DHCP server is responding to requests on a network that is L3 connected behind a router, the routers option must be specified. In general, it is not possible to automatically determine the IP address of the next hop router that faces the clients being served DHCP, hence the requirement for manual specification.tftp-server-nameCertain forms of customer premises equipment require BOOTP or TFTP provisioning (e.g., DOCSIS cable modems or WiMAX subscriber terminals). To accommodate this, the rXg incorporates a TFTP server and supports the delivery of DHCP responses with the requisite options. The value of the tftp-server-name option should be the IP address of the rXg that is closest to the end-user.
The value is the value that will be used when the key-value pair is appended to the DHCP request. For example, if max-lease-time
is chosen as the option name for a record, the option value should be set to the maximum number of seconds that a DHCP lease can be used by a end-user device.
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 option group field determines which DHCP responses will contain the key-value option pair configured in this record.
The following DHCP client options are currently supported:
Code | Option | Name | Description |
---|---|---|---|
1 | subnet-mask | Subnet Mask | Subnet Mask Value |
2 | time-offset | Time Offset | Time Offset in Seconds from UTC (note: deprecated by 100 and 101) |
3 | routers | Router | N/4 Router addresses |
4 | time-servers | Time Server | N/4 Timeserver addresses |
5 | ien116-name-servers | Name Server | N/4 IEN-116 Server addresses |
6 | domain-name-servers | Domain Server | N/4 DNS Server addresses |
7 | log-servers | Log Server | N/4 Logging Server addresses |
8 | cookie-servers | Quotes Server | N/4 Quotes Server addresses |
9 | lpr-servers | LPR Server | N/4 Printer Server addresses |
10 | impress-servers | Impress Server | N/4 Impress Server addresses |
11 | resource-location-servers | RLP Server | N/4 RLP Server addresses |
12 | host-name | Hostname | Hostname string |
13 | boot-size | Boot File Size | Size of boot file in 512 byte chunks |
14 | merit-dump | Merit Dump File | Client to dump and name the file to dump it to |
15 | domain-name | Domain Name | The DNS domain name of the client |
16 | swap-server | Swap Server | Swap Server address |
17 | root-path | Root Path | Path name for root disk |
19 | ip-forwarding | Forward On/Off | Enable/Disable IP Forwarding |
20 | non-local-source-routing | SrcRte On/Off | Enable/Disable Source Routing |
21 | policy-filter | Policy Filter | Routing Policy Filters |
22 | max-dgram-reassembly | Max DG Assembly | Max Datagram Reassembly Size |
23 | default-ip-ttl | Default IP TTL | Default IP Time to Live |
24 | path-mtu-aging-timeout | MTU Timeout | Path MTU Aging Timeout |
25 | path-mtu-plateau-table | MTU Plateau | Path MTU Plateau Table |
26 | interface-mtu | MTU Interface | Interface MTU Size |
27 | all-subnets-local | MTU Subnet | All Subnets are Local |
28 | broadcast-address | Broadcast Address | Broadcast Address |
29 | perform-mask-discovery | Mask Discovery | Perform Mask Discovery |
30 | mask-supplier | Mask Supplier | Provide Mask to Others |
31 | router-discovery | Router Discovery | Perform Router Discovery |
32 | router-solicitation-address | Router Request | Router Solicitation Address |
33 | static-routes | Static Route | Static Routing Table |
34 | trailer-encapsulation | Trailers | Trailer Encapsulation |
35 | arp-cache-timeout | ARP Timeout | ARP Cache Timeout |
36 | ieee802-3-encapsulation | Ethernet | Ethernet Encapsulation |
37 | default-tcp-ttl | Default TCP TTL | Default TCP Time to Live |
38 | tcp-keepalive-interval | Keepalive Time | TCP Keepalive Interval |
39 | tcp-keepalive-garbage | Keepalive Data | TCP Keepalive Garbage |
40 | nis-domain | NIS Domain | NIS Domain Name |
41 | nis-servers | NIS Servers | NIS Server Addresses |
42 | ntp-servers | NTP Servers | NTP Server Addresses |
44 | netbios-name-servers | NETBIOS Name Srv | NETBIOS Name Servers |
45 | netbios-dd-server | NETBIOS Dist Srv | NETBIOS Datagram Distribution |
46 | netbios-node-type | NETBIOS Node Type | NETBIOS Node Type |
47 | netbios-scope | NETBIOS Scope | NETBIOS Scope |
48 | font-servers | X Window Font | X Window Font Server |
49 | x-display-manager | X Window Manager | X Window Display Manager |
54 | dhcp-server-identifier | DHCP Server Id | DHCP Server Identification |
61 | dhcp-client-identifier | Client Id | Client Identifier |
64 | nisplus-domain | NIS-Domain-Name | NIS+ v3 Client Domain Name |
65 | nisplus-servers | NIS-Server-Addr | NIS+ v3 Server Addresses |
66 | tftp-server-name | Server-Name | TFTP Server Name |
67 | bootfile-name | Bootfile-Name | Boot File Name |
68 | mobile-ip-home-agent | Home-Agent-Addrs | Home Agent Addresses |
69 | smtp-server | SMTP-Server | Simple Mail Server Addresses |
70 | pop-server | POP3-Server | Post Office Server Addresses |
71 | nntp-server | NNTP-Server | Network News Server Addresses |
72 | www-server | WWW-Server | WWW Server Addresses |
73 | finger-server | Finger-Server | Finger Server Addresses |
74 | irc-server | IRC-Server | Chat Server Addresses |
75 | streettalk-server | StreetTalk-Server | StreetTalk Server Addresses |
114 | captive-portal-api | Captive Portal API | Captive Portal API URL |
The following DHCP server options are currently supported:
Option | Description |
---|---|
abandon-lease-time | Maximum amount of time (in seconds) that an abandoned lease remains unavailable for assignment to a client |
adaptive-lease-time-threshold | Specify the % of active leases before the server hands out only short min_lease_time leases |
always-broadcast | Always broadcast responses to clients, regardless of the broadcast bit in the request header |
always-reply-rfc1048 | Always respond with RFC1048-style responses |
default-lease-time | length in seconds that will be assigned to a lease if the client does not ask for a specific expiration time |
dynamic-bootp-lease-length | length in seconds of leases dynamically assigned to BOOTP clients |
filename | Name of the initial boot file which is to be loaded by a client |
get-lease-hostnames | Perform reverse lookup of IP to determine hostname |
infinite-is-reserved | |
one-lease-per-client | Automatically free any other leases the client holds when responding to a request |
ping-check | Ping the IP to ensure it is free before assigning to a client |
ping-timeout | Timeout in seconds to wait for the ping-check to complete |
server-name | Inform the client of the name of the server from which it is booting |
site-option-space | Determine from what option space site-local options will be taken |
stash-agent-options | Record the relay agent information options sent during the initial request message and behave as if those options are included in all subsequent renewal requests |
update-conflict-detection | |
max-lease-time | Maximum length in seconds that will be assigned to a lease |
min-lease-time | Minimum length in seconds that will be assigned to a lease |
min-secs | Minimum number of seconds since a client began trying to acquire a new lease before the DHCP server will respond to its request |
next-server | Address of the server from which the initial boot file is to be loaded |
use-host-decl-names | Supply the scope's host declaration name to the client as its hostname |
Custom DHCP Options
The vast majority of client devices require only basic DHCP in order to achieve network connectivity. Some operators may choose to use standard DHCP options that are defined in IETF RFC 2132 to deliver specific additional configuration. Standard DHCP options may be configured via the DHCP Options scaffold. Between basic DHCP and standard options almost all client devices will get everything they need. Infrastructure devices are a different story.
In some cases certain kinds of devices may require configuration to be delivered via non-standard DHCP options. This usually applies to thin, headless infrastructure devices that depend on a central controller or server such as VoIP handsets, VoD set top boxes, wireless access points, etc. Specialized infrastructure devices. Custom DHCP Options are usually used to deliver bootstrap configuration information such as the IP address and filestore location of initial bootstrap configuration.
The Custom DHCP Options scaffold enables operators to configure the rXg to deliver DHCP options that are not defined byIETF RFC 2132. Each record in the Custom DHCP Option scaffold adds an option to the custom option drop down list in the DHCP Options scaffold. The payload ( value ) to be delivered to the device is configured in the DHCP Options scaffold.
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 type , array and code fields enable the operator to define the headers in the DHCP option that is to being defined. When the array checkbox is enabled, the option will be defined as an array of the type designated. The values of the corresponding DHCP Options should be entered in comma separated format. DHCP vendor-specific option 43 as well as DHCP site-specific option codes between 128 to 254 may be configured to be delivered by the rXg. The exception to this is option 121, classless-static-routes. Static routes may be provided to clients by creating a custom DHCP option and specifying the type as an array of unsigned integer 8, and a code of 121. The value of the corresponding DHCP Option record may be 24,192,168,99,10,10,10,1, 24,172,16,32,10,10,10,2. This would provide a route to 192.168.99.0/24 via 10.10.10.1 and a route to 172.16.32.0/24 via 10.10.10.2. Refer to IETF RFC 3442 for more information.
If the operator desires to deliver payloads via vendor-specific DHCP option 43 then the type should be set to vendor-specific. In this case the code field should be configured to be the DHCP option sub-code that is desired. The settings of the type to vendor-specific implicitly defines the format of the payload to be hex. The payload that is configured by the value field in associated the DHCP Option will be automatically converted to hex from ASCII before being encoded into the option packet.
If the operator sets the type to anything other than vendor-specific then the code represents the site-specific DHCP option that must be between 128 and 254. This limitation is due to the fact that IETF RFC 2132 has already defined DHCP option codes from 0 to 127. The exception to this is the classless-static-routes option, code 121.
The payload of the Custom DHCP Option is defined in the option field of the DHCP Options scaffold and must fall within the range of acceptable possibilities for the given type.
Classes
An entry in the classes scaffold links one or more match rules to devices that are offered addresses from pools. When a match rule is linked, the specifications in the match rule are used to determine membership of the class.
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.
Classes are used to differentiate groups of clients based on matching a substring transmitted as part of the DHCP request or the MAC address of the requesting device. If two pools are created within the network address range associated with a single interface (e.g., 192.168.5.100-150 and 192.168.5.151-200), classes can then be used to populate devices into one of the two ranges based on the request. For example, all requesting devices presenting a dhcp-client-identifier
with a well known predefined prefix can be put into the first pool while all others into the second pool. This alleviates the need to collect and enter the MAC addresses of all devices in a group as fixed hosts in order to place them into a pool.
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 pools fields specifies the pool to place devices into that meet the criteria of the match rules specified by this class.
The match rules field links this class with the match rules that will determine membership.
Match Rules
An entry in the match rules scaffold creates a criteria for selecting DHCP requests to be a member of a class.
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 negate field configure the way the match rule specified by this record behaves. If negate is checked, a DHCP request is considered to be part of a class if it does not meet criteria specified by this match rule.
The logic field controls the way multiple match rules belonging to the same class behave. A setting of and
requires that all criteria be met. Conversely, a setting of or
allows a request to become part of a class if only one of the match rule criteria is met.
The option substring , substring offset and substring length fields control the matching criteria specified in the option value field. If option substring is unchecked, the data in the option value field must exactly match the payload of the DHCP option in the request in order for the request to be considered a match by this match rule. Inversely, if option substring is checked, the substring offset and substring length fields can be used to make a request considered a match if only a portion of the data in option value matches what is presented in the DHCP request. The values that are matched in the option substring are inclusive of the specified boundaries.
The option name and option value are the criteria that determine whether or not a request is a match for this rule. If a DHCP request contains a DHCP option name-value pair matching the data entered into option name and option value , then the DHCP request is considered a match for this rule.
For example, let us consider the case where the RGN distribution infrastructure is DOCSIS cable and composed of Motorola SURFboard cable modems with MAC prefix 00:0A:28, In order to simplify administration, the operator wishes to give all of the cable modems addresses in the 192.168.10.0/24 block and serve 172.16.16.0/24 to the end-users. To accomplish this, the operator would need to configure both DHCP pools and then associate the 172.16.16.0/24 pool with a class that has a match rule configured with:
- option substring - checked
- substring offset - 1
- substring length - 3
- option name - hardware
- option value - 000A28 At first glance, this would seem to be incorrect because we want to match the zeroth through the second byte of the MAC address inclusive. However, the hardware field has the Ethernet prepended onto the MAC address as the zeroth byte. Therefore the actual MAC address is the first to the seventh of the _hardware_field.
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 class field specifies the class for which this matching rule should be used to determine membership.
Relay Servers
An entry in the Relay Servers scaffold enables the DHCP relay feature for the specified interface. DHCP relay allows an rXg to proxy DHCP requests to an upstream DHCP server rather than managing a DHCP pool locally. DHCP relay cannot be used in conjunction with the DHCP server (pools and fixed hosts).
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 server IP field configures the IP address of the upstream DHCP server that will respond to the proxy DHCP requests.
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 interfaces and VLANs fields specify the local physical and logical interfaces to proxy DHCP requests to the server specified by server IP.
DNS
The DNS view contains the scaffolds to configure the rXg core services related to the domain name system.
The rXg integrates a dynamic DNS client that supports all of the major third party dynamic DNS services. Dynamic DNS is an essential part of deploying an rXg in an environment where the uplink address is dynamically assigned and may change.
Many of the rXg services (most notably, the forced browser redirect), require DNS resolution of a domain name to the IP address of the WAN uplink. If the IP address of the WAN uplink is configured via DHCP, it is critically important to reconfigure the DNS whenever the assigned IP address changes. The simplest way to accomplish this is to use the rXg dynamic DNS client.
The rXg also incorporates a fully featured DNS server. The operator can configure the rXg to be a primary, secondary or tertiary domain name server for any domain. Before using the DNS server features of the rXg, it is highly recommended that the administrative staff be familiar with the deployment and operation of the domain name system. Incorrect configuration may render the rXg inoperable. An excellent reference on the domain name system is DNS and BIND (ISBN 0596100574) by Cricket Lui and Paul Albitz.
To configure the rXg as a primary domain name server, the DNS glue records for the domain name must contain the IP address of an rXg uplink. To configure the rXg as a secondary name server, create a DNS zone specifying the primary name server in the master hostname field.
When using the rXg as a primary domain name server, proper DNS glue records must be in place. Most DNS registrars have a web application that enables glue record changes. Updates to glue records sometimes take days to propagate so it important to use a manually assigned static IP address for the rXg uplink.
With the DNS glue records in place, a new entry must be added to the DNS zone scaffold. Set the master hostname to the host name of the rXg and the hostmaster email to something appropriate. At a minimum, two entries must be added to the DNS records scaffold (the nameserver and address records for the rXg itself). Additional resource records may be added so that the rXg provides resolution of desired hostnames.
Dynamic DNS Clients
An entry in the Dynamic DNS scaffold enables the rXg to update third-party dynamic DNS services with the latest WAN IP address configuration. In most cases, a DNS record must be created on the third party dynamic DNS service before updates can be made by the rXg.
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 protocol field determines the communication protocol that will be used to perform dynamic DNS updates. Most of the popular dynamic DNS services have developed their own proprietary protocols. In most cases, the protocol is synonymous with the service, making the choice obvious.
The login and password fields are the authentication credentials that are supplied to the dynamic DNS service when sending updates. These credentials must match those of the account at the third party service in order for updates to be authenticated and accepted.
The hosts field is a comma-delimited list specifying the DNS name(s) that are to be updated. Typically this will be the same DNS name that is specified in the domain name field of the device options scaffold.
The static and wildcard checkboxes modify the payload of the update message sent to the dynamic DNS service. Some services permit automated update of statically configured IP addresses. Usually there is a stipulation that the update frequency must be much lower than that of a dynamic IP. In addition, some services permit the use of wildcard DNS names so that a single entry can cover several hosts. If either kind of record is established on the third party dynamic DNS service, the appropriate checkbox must be set.
The protocol server field is an optional parameter that can be used to specify an alternate destination for dynamic DNS update messages. Since most dynamic DNS services use their own proprietary protocol, selecting a protocol usually determines the destination for the messages. This field enables the operator to override the default destination.
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 IP address sent to the dynamic DNS service in an update message is the uplink IP address of the default rXg route. In single uplink scenarios, this is the network address that is statically associated with the uplink or the dynamic address acquired by the uplink via DHCP. In multiple uplink scenarios, the choice of the default route is controlled by the priority setting of the uplink.
DNS Zones
An entry in the DNS zones scaffold defines a new domain that the rXg integrated DNS server will respond to.
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 domain name field configures the domain that this record will enable responses to.
The master hostname must be set to the fully qualified domain name of the primary master nameserver for this domain. If the rXg is to be the primary master nameserver for the domain, an address record must be configured in the DNS records scaffold.
The hostmaster email field specifies the administrative email address that is reported by the DNS server.
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.
DNS Records
An entry in the DNS records scaffold creates a new record in a zone specified in the DNS zones scaffold.
The host is the host name for this record. The host name is the parameter that is matched when a DNS query is made.
The type field determines the DNS resource record type. The list of dns record types and their function is defined by a series of RFCs published by the IETF.
The dynamic data and data fields define the payload for the DNS resource record. The use of dynamic data and data are mutually exclusive. If a dynamic data field is chosen from the drop down, the response to a query matching the host specified in this record will be the IP address of the uplink specified by the drop down. If data is populated and no dynamic data field is specified, then the response will contain the static payload configured in the data field.
The zone field specifies the DNS zone that this record will be attached to. If "DNS Override" is selected, the rXg will resolve this specific record to the data listed, but all other requests for the same domain will be forwarded on for normal DNS lookup via upstream providers. This avoids having to maintain all records for a domain when attempting to override a single A record.
Domains may be "black-holed" by creating two CNAME DNS Override records, one for domain.com and one for *.domain.com, and setting the data field for both records to "." (no quotes).
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 complete reference of DNS resource records is found in BIND 9 DNS Administration Reference Book (ISBN 0979034213) by Jeremy Reed.
DNS Server
Entries in the DNS Server scaffold define configuration profiles for the rXg integrated DNS server.
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 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.
A properly configured DNS server takes part in a hierarchy of servers starting with the operator of the next hop network all the way to the root DNS servers. By default, the rXg is properly configured to forward requests to the next hop DNS servers. Clearing the request forwarding check box will force the rXg DNS server to make requests directly to the root. Avoid this configuration when possible.
The request forwarding order drop down menu determines the which DNS servers the rXg will query as the next hop. Dynamic servers are those that have been provided via WAN DHCP configuration. Static servers are those that have been manually configured by the operator using the DNS Servers scaffold of the WAN view of the rXg console. Choosing the dynamic,static option tells the rXg to query the dynamically assigned servers first and then the statically assigned servers. Choosing the static or dynamic options tells the rXg to limit queries to the selected set of servers. When multiple uplink control is deployed, the set of dynamic DNS servers is limited to those that are presented by the DHCP server of each pipe. Furthermore, the set of statically configured servers must be accessible via all pipes. This drop down has no effect unless request forwarding is enabled.
The originate queries from port 53 check box configures the DNS server so that upstream UDP queries originate from port 53. This setting may be required if a strict firewall is positioned between the rXg and the upstream DNS server(s).
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
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.
Example: Setup CloudFlare Dynamic DNS
Before we begin we must obtain an API Key from CloudFlare. Navigate to their site and login with your credentials. Click on the person icon in the upper right-hand corner.
Click on "My Profile".
Click on "API Tokens".
Click "View" on the "Global API key".
Enter your CloudFlare password when prompted.
Copy your API Key.
In the rXg navigate to Services::DNS and create a new Dynamic DNS Client.
Give the record a Name. Change the Protocol field to CloudFlare. Enter your email address into the Login field. Enter your API key into the Password field. The Host field is the FQDN to be updated in CloudFlare, and the Zone field is the root domain of the FQDN. Click Create.
When setup the scaffold will update when there is a change.
VPN
The VPN view presents the scaffolds associated with configuring the IPsec and OpenVPN services integrated into the rXg.
OpenVPN Servers
Entries in the OpenVPN Servers scaffold define configuration profiles for the rXg integrated SSL(TLS) VPN.
OpenVPN is an industry standard, open-source software application that the rXg leverages to implement virtual private network (VPN) techniques to create secure point-to-point connections in a routed configuration. It uses a custom security protocol that utilizes SSL/TLS for key exchange. It is capable of traversing network address translators (NATs) and firewalls. The OpenVPN functionality allows peers to authenticate each other using certificates and/or username/password. When used in a multiclient-server configuration, it allows the server to release an authentication certificate for every client, using signatures and certificate authority. It uses the OpenSSL encryption library extensively, as well as the TLS protocol, and contains many security and control features.
https://community.openvpn.net/openvpn/wiki
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.
Each server represents a virtual network interface on a subnet specified by a related Network Address. A separate VPN instance exists for each configured server. A Network Address that is assigned to an OpenVPN interface cannot be configured on a traditional ethernet Interface or VLAN. All servers/networks operate in OpenVPN's TUN (tunnel) mode, which transports only layer 3 IP packets.
If the default gateway field is checked the client will use the VPN interface's IP as its default gateway and DNS server, and route everything over the VPN. An OpenVPN server's Network Address behaves similarly to any other routed subnet behind an ethernet interface or VLAN, in that IP clients behind it are subject to Policy enforcement. For example, creating an IP Group and Landing Portal Policy without a subnet filter for the VPN network would permit the client to access all networks. Conversley, a portal-enabled Policy could be deployed for the VPN client's network. If gateway redirect is not enabled on the server, then it will push routes for all other local networks to a VPN client, which allows it to route through the normal Internet whilst also having knowledge of networks behind the VPN. Note that like any other traditionally-attached subnet, or when the VPN is the default gateway, the routes pushed to the client do not necessarilly ensure firewall access to all networks. In general, an OpenVPN client can also manipulate its routing table independently on a per-client basis.
Authentication from a client may be multi or single-factor via certificates ( require certificate ) and/or username/password ( require login ). If certificates are required, clients must have a unique certificate installed to authenticate. The certificate must be signed by the same CA as the OpenVPN Server's certificate. If multiple devices need to use the same client certificate, the allow duplicate certificates field must be checked, otherwise only one connection per certificate Common Name is permitted. Requiring a unique certificate per client is more secure, but requires each client to have a unique configuration.
If client-to-client behavior is enabled, then clients on the same virtual network can route to each other as if the firewall was disabled. This does not include L2 traffic. Otherwise, if this behavior is disabled, all traffic is forced to route through the rXg and is thus filtered according to Policy enforcement. This should only be enabled when_everyone_ connecting to the same OpenVPN Server should be allowed to communicate.
Configuring the Admin Roles or Account Groups fields permit corresponding Admins and/or Accounts access to the VPN via login. If client certificates are required, the login is only half the authentication process. If client login is not required then these selections are ignored. It is recommended that operators (Admins) and end-users (Accounts) connect to separate OpenVPN Servers. In the case where an OpenVPN Server has Admins and Accounts allowed, an Admin having the same login as an Account always takes precedence for login and instrumentation purposes.
The port and protocol fields define how a client initially connects to the VPN server. A TCP and UDP server may be configured to run on the same port. There are advantages and disadvantages to either protocol (OpenVPN tcp vs udp).
An OpenVPN Server must have a Certificate configured. This identifies the server's certificate and private key in additon to the Certificate Authority (CA) that establishes the PKI used to trust clients. The selected Certificate must be associated with and created from a local Certificate Authority. The certificate must be marked for server usage, meaning it was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules. This can be done when creating the Certificate Signing Request (CSR). This is an important security precaution to protect against a man-in-the-middle attack where an authorized client attempts to connect to another client by impersonating the server.
The cipher and digest options affect the strength of the underlying encryption, where a longer key length increases security and reduces throughput performance. Data compression is enabled by default and is very efficient when LZ4 is employed, which reduces the bandwidth requirements of the VPN at the expense of additional overhead on the client and server.
The TLS-auth option adds an additional layer of HMAC authentication on top of TLS to mitigate DoS and other attacks againist the TLS layer. This is accomplished by including a unique key that resides on top of TLS. The key is generated behind the scenes when an OpenVPN Server is created, and included in the client config output. If a client is configured manually and this is enabled, then the operator must obtain the key from the record via scaffold show action.
By default, access to rXg services are either limited to the LAN or disabled entirely. In certain cases, the operator may desire to permit accessibility to services over the WAN and/or LAN. To enable access to rXg services over the WAN, the operator should specify one or more WAN targets containing the list of allowed hosts and then set the visibility appropriately. If no WAN target is specified and WAN visibility is enabled, any node on the WAN may connect to the service. It is highly recommended that this wide-open configuration be avoided to ensure system security. If LAN visibility is included then all authenticated nodes on the LAN may access this service.
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.
Clicking the Download Config link will generate an OpenVPN config (.ovpn) file containing the necessary client connection parameters based on the server's configuration, including the Server certificate. Currently, if a client certificate is required, it must be generated manually via the local CA and installed in the client along with the config file.
IPsec VPN
IPsec is an industry standard mechanism that enables secure communication between two nodes or networks that are connected by a potentially insecure IP transit. The rXg supports bidirectional site-to-site IPsec VPNs between rXgs and between rXgs and other kinds of routers. In addition, the rXg may be configured to be a concatenator for host-to-site VPNs originating from nearly any operating system.
Site-to-site VPNs are typically used to enable secure bidirectional communication between two private IP blocks that are behind different routers that are located in geospatially distinct locations. For example, if a WISP has three distinct fixed wireless broadband coverage areas, all three could be linked together via site-to-site VPNs. This could be used as part of a revenue generation strategy such as allowing business customers to access their systems from home for an additional fee.
Site-to-site VPNs are very useful in geospatially diverse deployments that are connected via a central cluster controller. Establishing site-to-site VPNs between the rXgs and the cluster controller enables the operator to easily access all nodes at any part of the network. It is important to keep in mind that the private LAN addresses blocks behind the various rXgs be kept distinct as having the same private LAN block behind two rXgs would cause routing confusion.
Host-to-site VPNs are often used by operators for remote administration. An operator that is on the WAN side of a rXg may use host-to-site IPsec VPNs to directly access machines that are connected to a private address range. In a typical deployment, LAN equipment is assigned IP addresses from private ranges that cannot be reached from the WAN. An operator who is on the WAN side on the rXg (e.g., away on business) that wishes to have complete and direct access to the LAN equipment private address range would setup a host-to-site IPsec VPN using the rXg as the concatenator.
Host-to-site VPNs are also used as a revenue generation mechanism as they are typically sold as a premium service or as a value-added extra part of business class service. End-users originating traffic from the LAN side of the rXg may create a host-to-site VPN using the rXg as a concatenator to protect their traffic from sniffers present in the distribution network. Of course, end-users may also be sold host-to-site VPNs as a mechanism for remote connectivity to nodes addressed on a private LAN.
The rXg uses an industry standard reference implementation of the IPsec suite. Site-to-site VPNs are easily established between an rXg and nearly any other router that supports IPsec VPNs. In addition, site-to-site and site-to-host VPNs may be established between the rXg and almost any operating system released since 2005. Most operating systems have a built-in IPsec stack that is meant to be configured by a trained and certified specialist. However, VPN client software (e.g., Greenbow for Windows and IPsecuritas for Mac OS X) simplify the process to the extent that anybody with a working knowledge of basic TCP/IP can accomplish the task.
IPsec Tunnels
An entry in the IPsec tunnels scaffold is used to configure a site-to-site IPsec VPN.
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 specification field selects the credential and encryption settings for this IPsec tunnel. It is critically important to ensure that the settings in the chosen IPsec specification matches those of the node at the other end of the site-to-site VPN created by this IPsec tunnel.
The Pre-Shared key and Certificates fields are used to configure the certificates or pre-shared key that will be used for authenticating IPsec tunnels that use this IPsec specification. The operator may choose to use one or more certificates or a pre-shared key but not both. If one or more certificates are chosen, then the node at the other end of the IPsec tunnel must have the matching private key. If a pre-shared key is chosen, then the node at the other end of the IPsec tunnel must have the exact same pre-shared key programmed.
The addresses and static routes checkboxes specify which LAN address blocks will be