Home Products Store Blog Users Contact

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:

• bin folder contains all the binaries that control server function.
• data folder contains PostgreSQL cluster data, configuration files, backups, updates, log files etc. This is only folder safe for your use where you can save data. All other folders are deleted when upgrading or uninstalling program.
• data/pgdata is location of PostgreSQL database cluster. Do not edit it or copy it as a method of making backup unless server is shut down.
• data/backup folder is where database snapshots are located. If you are making backups of your own, only files from this folder are needed for you to be able to restore whole system. Rest of the installation is expendable.
• shared folder contains all other files used by BlissRADIUS and contains same files on Windows and Linux. It includes scripts, language translations, database schema etc.
• rest of the files found are OS specific and do not concern this manual.

And these are files from bin folder:

• bin/bliss_ctl.exe is server control daemon and your main tool. It starts all components, makes sure they are running even in case of failure and restarts failed components.
• bin/bliss.exe is core of the server. You can run it manually, but database must be running and you can't leave it unattended. Use it only for debbuging purposes.
• bin/bliss_restore.exe is what you use to restore backup files.
• bin/bliss_password.exe is there in case you need to reset (admin) passwords in case you forget them.
• bin/bliss_svc.exe is Windows specific file and is registered as service. It is something you don't ever need to use, but will see often in task manager.

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:

• costly to implement in both expertise and time
• error prone due to increased system complexity
• have increased maintenance cost due to extra components
• do not offer 100% reliability and require human supervision at one point or the other during disaster

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:

• keep automated backup enabled, hourly if needed and your business model is high volume
• always have backup uploaded off server to remote FTP
• read in advance on how to restore backup to have idea what to do when it is needed
• periodically check automated backup logs using Monitoring > Syslog page in portal and check backup files FTP upload folder

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:

• monitoring replication and slave server are extra tasks you must add to your daily routine
• in most cases, speed difference between switching to slave server and manual backup restoring is minimal. Only when your database grows to certain size does slave replication offers time saving. Eg. backup file size of 250 MB might match database size of more than 4 GB which equals history records of 5 or 10 years worth of work for medium sized providers. All this can be restored in just over 5 minutes from backup file.
• constant replication does offer advantage of no lost data compared to scheduled backup, but this can be greatly minimized by configuring backup to run hourly during work hours and less frequently during the night. However, data replication is useless in certain scenarios where data on master server is corrupted, eg. accidentally deleted. Switching to slave server with identical data is of no practical use

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.