Skip to content

export_import_mechanism.asciidoc

Latest commit

 

History

History
185 lines (143 loc) · 7.47 KB

export_import_mechanism.asciidoc

File metadata and controls

185 lines (143 loc) · 7.47 KB
Raw
Table of Contents

This section covers export/import mechanism available since PacketFence 11.0. It can be used to automate parts of upgrades or to restore PacketFence installations.

Assumptions and limitations

  • Export is supported on any PacketFence version above 10.3

  • With export from 10.3, import is supported on any PacketFence version after 11.0 except if using mariadb-backup for mysql backup.

  • If using mariabd-backup and wanting to jump to Debian 12 (packetfence 14.0 or later), it will be necessary to:

    • be at least on Packetfence version 11.0

    • follow these steps in order to backup the database with the right mariadb-backup version.

  • The import process needs to be done on a standalone server. Restoring directly to clusters is currently unsupported

    • NOTE: Once restored to the standalone server, it can be made a cluster by joining other machines to it and creating the cluster.conf but this is relatively advanced and out of scope of this document

  • Restoring on a fresh install of PacketFence is recommended although restoring on an existing instance can work but results may vary

  • The import process will not modify network cards configuration of the server: it will only update PacketFence IP configuration. Recommend defining targeted IP addresses on network cards before running import process even if it can be done at end of import process.

  • The import process will not join server to Active Directory domains automatically. Rejoin server manually.

  • The import process will only restore the files that can be edited via the admin interface which include:

    • Standard configuration files in /usr/local/pf/conf/*.conf

    • Connection profiles HTML templates in /usr/local/pf/html/captive-portal/profile-templates/

    • Standard certificates

      • /usr/local/pf/conf/ssl/*

      • /usr/local/pf/raddb/certs/*

  • Here is a short list of the configuration files that will not be restored. Changes to these files need to be migrated manually. This list is not meant to be complete:

    • /usr/local/pf/conf/radiusd/*

    • /usr/local/pf/conf/log.conf

    • /usr/local/pf/conf/log.conf.d/*

    • /usr/local/pf/conf/iptables.conf.tt (but /usr/local/pf/conf/iptables-custom.conf.inc and /usr/local/pf/conf/ip6tables-custom.conf.inc are restored)

    • /usr/local/pf/conf/cluster.conf

Warning
 The import process will never replace a virtual IP address in configurations. If the export has been done on a cluster, ensure there are no references to virtual IP address of this cluster after import has been completed.

Export on current installation

Note
 When in a cluster, perform this process on the first member of the incoming addresses of the database cluster. To find the member, run show status like 'wsrep_incoming_addresses'; inside the MariaDB instance and the first IP will be the one where to perform the export process.

Installation (for PacketFence version 10.3 only)

On PacketFence version 10.3, install packetfence-export package using following instructions:

RHEL / CentOS based systems only
yum localinstall https://www.packetfence.org/downloads/PacketFence/RHEL8/packetfence-export-{release_minor}.el8.noarch.rpm
Debian 9 systems only
wget https://www.packetfence.org/downloads/PacketFence/debian/packetfence-export_{release_minor}.deb
dpkg -i packetfence-export_{release_minor}.deb

Start the export process

The export process will try to use files created by the nightly backup done at 00:30am everyday. If this is fine and the latest data is not needed, then skip this step. Otherwise to have the latest data and configuration in the export, run:

/usr/local/pf/addons/exportable-backup.sh -f /tmp/export.tgz

The command above will create the export archive in /tmp/export.tgz. It will now be necessary to copy this file to the new server using SCP or the preferred mechanism.

Import on new installation

First have a PacketFence installation with latest version done on a standalone server following the instructions in our install guide. It is not necessary to go through the configurator unless wanting to modify IP settings of the server.

Warning
 If wanting to use the first step of the configurator to configure the server, do it before running the import.

Note on Mariabackup

The import script could try to install Mariabackup to import the database dump. If that is the case, it will remove it at end of import.

Consequently, if Mariabackup was installed before running the import script, ensure that Mariabackup is still installed at end of import.

Start the import process

The import script will guide through the restore of the database, if necessary it will assist with the configuration files and adjust the PacketFence IP configuration.

To start the import process using the export archive made on the current installation:

/usr/local/pf/addons/full-import/import.sh -f /tmp/export.tgz

Once the process is completed, the following should appear:

Completed import of the database and the configuration! Complete any necessary
adjustments and restart PacketFence

If that’s not the case, check the output above to understand why the process failed.

If any issues are experienced during import, run it again.

If all goes well, restart services using following instructions.

Import options

Without any option, import.sh performs a full import (database and configuration) and upgrades them to the running version when the export comes from an older one.

-f, --file <archive>

Path to the export archive to import (mandatory).

--db

Import only the database.

--conf

Import only the configuration.

--restore-as-is

Restore the export exactly as it was backed up. Intended for restoring onto the same PacketFence version: no database, MariaDB or configuration upgrade is performed, the backup’s database host and port are kept, and no question is asked (fully non-interactive).

--skip-adjust-db-conf

On a configuration import, keep the backup’s database host and port instead of rewriting them to localhost. Useful on a cross-version import that must preserve a non-local database host. (--restore-as-is already implies this.)

Additional steps to build or rebuild a cluster

To build or rebuild a cluster, follow instructions in Cluster setup section.

If the previous installation was a cluster, some steps may not be necessary to do. The export archive will contain the previous cluster.conf file.

Warning
 if Mariabackup was installed before running the import, it’s possible that it needs to be reinstalled.