03. 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
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:
binfolder contains all the binaries that control server function.
datafolder 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/pgdatais location of PostgreSQL database cluster. Do not edit it or copy it as a method of making backup unless server is shut down.
data/backupfolder 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.
sharedfolder 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/bliss_ctl.exeis 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.exeis 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.exeis what you use to restore backup files.
bin/bliss_password.exeis there in case you need to reset (admin) passwords in case you forget them.
bin/bliss_svc.exeis 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
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
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
bliss_ctl.exe start (or same command on Linux without
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.
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
BlissRADIUS has automated backup system that creates files in
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
rsync or scheduled copy from local backup folder to network drive.
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:
This action will rename existing database folder
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
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:
- Get any Windows or Linux machine you have at your disposal that satisfies installation requirements.
- Change IP address of your new host to match address of your crashed RADIUS server.
- Download latest BlissRADIUS installation and install it on new host
- Copy latest backup file you got onto the host.
bliss_restore.execommand as described.
- 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:
- configure PostgreSQL master-slave replication (using Slony or similar) from BlissRADIUS to slave server
- build detection system that signals when primary server is down
- 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)
- 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:
Prepare new computer and install fresh BlissRADIUS server.
Copy latest backup file from current to new computer.
Restore backup file into server on new computer.
Run uninstall link in Start Menu on Windows, or
on Linux. Contents of
data folder will not be deleted.
Copyright © 2014 - 2018 LightBulb Software™ All Rights Reserved.
- BlissRADIUS Embedded™ 1.7 maintenance release is out.
- BlissRADIUS Embedded™ 1.6 is out with incremental improvements and new usability features.
- BlissRADIUS Embedded™ 1.5 is released with new proxy features and advanced caching for better resilience.
- BlissRADIUS Embedded™ 1.4 maintenance release is out! No significant changes, lot of small fixes. And we finally updated documentation on custom integration.
- BlissRADIUS Embedded™ 1.3 is released. It is incremental release with more fixes and tweaks than new features.
- BlissRADIUS Embedded™ 1.2 is out! It brings many performance and stability enhancements.
- 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.
- 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.