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 protocol field specifies the application layer protocol that will be used to transport the file.

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

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

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

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

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

Receiving Backups

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

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

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

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

Restore

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

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

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

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

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

Config Templates

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

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

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

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

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

Configuration Syntax

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

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

For example, to add an administrator:

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

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

DeviceOption:
- name: Default
  time_zone: America/Chicago

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

license_key: |
  abcdQabcduUzuo5IxtjuDabcdx6zVfEgnjl30Q4lDiabcdpCYmNrQa5x
  ...
  xKdOy1PabcdHydNCvs5CU5JLRabcdn0yHZIpv6FvDxFdmku7XiDEGuI=

Advanced Usage

Top-Level Data Structure

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

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

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

Nested Associations

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

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

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

Custom Lookups and Mutating Records

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

Admin:
- login: someuser
  admin_role: Super User

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

Admin:
- _lookup:
    login: sumusr
  login: someuser

Only Update Existing Records

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

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

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

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

Delete Existing Records

A config template that contains an _delete key can be used to delete an existing record. See the following example: Admin: - login: testadmin _delete: true The template above would look for an existing administrator account with the name "testadmin" and delete the administrator if it does exist.

Association Lookups

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

Supported Model/Scaffold Keys

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

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

Supported Smart Keys

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

Use Config Template to Bootstrap New rXg Installation

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, and shell to execute a command on the rXg.

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

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

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

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

Execute the Ansible Playbook:

ndk@MBP ansible % ansible-playbook adminmgmt.yml

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

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

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

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

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

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