03. Administration manual

Administration manual

Administration manual is something sys admins should learn well before going to production with BlissRADIUS. It gives knowledge about daily maintenance and important tasks of keeping server up & running and data safe.

Program folder and files

Installation will be located in c:\BlissRADIUS on Windows or /blissradius on Linux by default. Both systems will share identical directory structure. .exe files on Linux have no extension:

bin/
    bliss.exe
    bliss_ctl.exe
    bliss_restore.exe
    ....
data/
    pgdata/
    backup/
    update/
    ...
shared/
    lang/
    web/
    ...
...

Here is quick description of each folder:

And these are files from bin folder:

Executing console commands

On Windows you will need to open console windows open Run > cmd.exe. Then navigate to bin folder by typing cd c:\BlissRADIUS\bin

On Linux open shell and type cd /blissradius/bin and you are ready to go.

How to start and stop server

On Windows, you can use Program Menu > BlissRADIUS shortcuts. You can use Control Panel > Services > BlissRADIUS too.

On both Windows and Linux you can do it manually as well, using console. All command programs are in bin folder.

To start, stop or query service use bliss_ctl.exe. It runs server in background and redirects console output to log files. It will automatically restart process if unexpected crash occurs. To start all components execute bliss_ctl.exe start (or same command on Linux without .exe).

To start only database, query status, and shut down everything:

bliss_ctl.exe start db
bliss_ctl.exe status
bliss_ctl.exe stop

If you want to manually run server and see console output for debug purposes, use bliss.exe. You need to only start database server before that. Shut down everything just in case as first step. Example:

bliss_ctl.exe stop
bliss_ctl.exe start db
bliss.exe

Ordering of arguments for bliss_ctl.exe program is flexible. bliss_ctl.exe start db and bliss_ctl.exe db start will do same thing.

Important: bliss.exe is foreground process. If you log out of shell account (or close console window) it will terminate process. Do not use this way to run unattended server. Use bliss_ctl.exe instead.

Automated backup

BlissRADIUS has automated backup system that creates files in data/backup folder. Each file is named by creation date and contains all necessary data to restore your server. Backup system has option to upload files to FTP server as well.

Backup is created daily at midnight by default and BlissRADIUS takes care that files are rotated and that max total size limit is not reached. It contains PostgreSQL dump of database in compressed format, as described in pg_dump command. Exact time, frequency, number and size of backups can be set in admin portal.

If FTP backup is enabled, BlissRADIUS will try to synchronize contents of FTP backup folder to the local one. This way, number and total size of files on FTP server should match limits set by configuration.

Backup operations are performed while BlissRADIUS is running. There is no interruption to normal usage.

Backup files contain gzip-ed (compressed) data. Compressing them further is pointless.

Important: Regularly copy backup files off site. Built in FTP backup is most practical option. Alternative include using synchronization tool like rsync or scheduled copy from local backup folder to network drive.

Restoring backup

To restore backup you will need to run bliss_restore.exe command with single argument that is path to backup file. It is not required to shut down BlissRADIUS server during this operation. Example:

bliss_restore.exe ../data/backup/20121010_163000.bin

This action will rename existing database folder data/pgdata to data/pgdata_old_1362279783 (or similar name with time stamp) before restoring backup. In case restoration fails and you wish to revert to old database, you must stop server and rename folders back.

Path to backup file must be either absolute or relative to bin folder.

Time required for whole operation varies greatly and depends on backup file size and system stats. Rough estimate for 2.3 GHz x 4 processor is around 1 minute for 50 Mb backup file. Backup of that size might match 1000 user production server working for couple of years.

Full disaster recovery steps

This is scenario when your server has crashed and is unable to boot up or run correctly. Procedure for setting up new server would be:

  1. Get any Windows or Linux machine you have at your disposal that satisfies installation requirements.
  2. Change IP address of your new host to match address of your crashed RADIUS server.
  3. Download latest BlissRADIUS installation and install it on new host
  4. Copy latest backup file you got onto the host.
  5. Execute bliss_restore.exe command as described.
  6. Log in to web portal and check if things are running smoothly.

If there are unforeseen problems, contact us and we will help in no time.

Partial disaster recovery steps

This is scenario usually involves accidental or intentional data deletion or modification that you wish to undo. Host machine is able to run properly, only thing need is reverting to point in time before accident.

This is more common scenario as it can be caused by operators from BlissRADIUS admin portal.

Procedure match previus chapter starting from step 4.

Server redundancy and safety tips

ISP services are rarely left unattended for any significant period of time and usually there is always administrator on duty. BlissRADIUS recovery system is built on idea that when disaster hits, it always requires human intervention for fixing or validating successful resolution. Even fully automated self-recovering solutions may not be satisfactory because they are:

BlissRADIUS aims to provide simple and highly effective tools for manual recovery. It is much quicker for administrator to do full restore from backup on to new server machine than alternative solutions like cloning or rebuilding RAID setup. This is exactly the reason why BlissRADIUS comes with no-dependency small installer, quick installation process and highly optimized and simple backup/restore procedure.

To keep server safe, we advise that you work along these lines:

BlissRADIUS has spotless record on safety and no data was lost so far with setups that had functioning automated backup.

For those that wish to go down the line of automated solutions, these would be steps:

  1. configure PostgreSQL master-slave replication (using Slony or similar) from BlissRADIUS to slave server
  2. build detection system that signals when primary server is down
  3. build switch system that redirects all RADIUS and web traffic to secondary server when signal is received (or replaces addresses of primary and secondary server)
  4. notify administrators of what is going on

Even with automated solution like this we strongly advise that you keep automated backup enabled. You must be aware of:

Upgrading program to newer version

Download installer for newer version and run it. It will take care of all required tasks. During upgrade all contents of data folder will be unmodified. If you wish to revert to old BlissRADIUS version for whatever reason, just re run old installer.

You can not revert to version that is too old. Each version has its database revision number and once you upgrade your server to next number, you can't go back. If you have any doubts, contact us.

Migrating server to different computer

Automated backup contains all data you need to migrate to different computer. You must read sections Automated backup and Restoring backup to know how to do it. Operation is straight forward:

  1. Prepare new computer and install fresh BlissRADIUS server.

  2. Copy latest backup file from current to new computer.

  3. Restore backup file into server on new computer.

Uninstalling program

Run uninstall link in Start Menu on Windows, or uninstall.sh script on Linux. Contents of data folder will not be deleted.

2018-06-27
BlissRADIUS Embedded™ 1.6 is out with incremental improvements and new usability features.
2018-03-31
BlissRADIUS Embedded™ 1.5 is released with new proxy features and advanced caching for better resilience.
2018-03-04
BlissRADIUS Embedded™ 1.4 maintenance release is out! No significant changes, lot of small fixes. And we finally updated documentation on custom integration.
2017-12-02
BlissRADIUS Embedded™ 1.3 is released. It is incremental release with more fixes and tweaks than new features.
2017-06-05
BlissRADIUS Embedded™ 1.2 is out! It brings many performance and stability enhancements.
2016-11-05
BlissRADIUS Embedded™ 1.0 is out! This is important milestone that marks more than a year of successful production use. 1.0 is backward compatible with 0.x and brings incremental improvements and bug fixes.
2016-09-26
BlissRADIUS Embedded™ 0.9 brings integration with Blesta billing. There is also a new "local" standalone mode to run program without third-party billing. Manual has been updated accordingly.