The missing command-line tool for UrBackup Server. It provides valuable insights into the utilization of data, clients' status and activities, and helps administrator to identify, troubleshoot and resolve issues that may arise within the system.
You have the option to use this Deno application in two ways: either as a
self-contained compiled executable or as a script file that runs with Deno.
Although it is not entirely feature-complete, the Main
branch should be stable
and has been utilized daily on a bunch of servers.
The following features have been implemented:
- Utilizes the standard API provided by UrBackup Server, so there is no need to change or install anything on the server.
- You can choose to run the tool directly on the server or remotely over the network from your workstation.
- The output can be presented in various formats, and you have the ability to sort data and apply filters as needed.
- You can execute the tool manually when required, or you can use it with an automated monitoring solution such as Zabbix.
- Information about all clients, including clients with "OK" or "failed" backup status (as seen in the server web UI).
- Information about clients without a recent backup (referred to as stale clients), with thresholds that can be configured in urbstatus.
- Information about clients without any finished backups (blank clients) and clients not seen for a long time (void clients), with a threshold that can be configured in urbstat.
- Information about online, offline, and active clients.
- Information about current, last (finished), and paused activities.
- Information about storage usage.
- All information about a selected client can be obtained at once.
Some of the features that are planned for implementation:
- The ability to query multiple servers simultaneously.
- Creating a repository for deb and rpm systems using OBS.
If you have any suggestions for new features that you would like to see in future updates, please don't hesitate to share them with me. Additionally, if you encounter any bugs or issues while using the tool, please report them through GitHub.
Please keep in mind that this demo may represent an older version of urbstat
with different command names and options.
Retrieve the number of clients with failed image backup:
failed-clients --skip-file --format number
failed-clients --skip-file --format number --ask-pass
failed-clients --skip-file --format number --user urbstat
Retrieve clients with a file backup that is older than 24 hours (1440 minutes) since the last backup:
stale-clients --threshold-file 1440 --sort name --format table
Retrieve clients that have not been seen for more than 48 hours (2880 minutes):
void-clients --threshold 2880 --sort name --format table
Retrieve a list containing the names of clients that have not yet completed any backup:
blank-clients --format list
Retrieve the current activity with the longest estimated time of arrival (ETA).:
current-activities --max 1 --sort eta --reverse --format table
Get a table with the last activities of the "office" client sorted by size:
last-activities --client office --sort size --format table
Retrieve the five longest running activities that have been completed:
last-activities --max 5 --sort duration --reverse --format table
Get three clients with biggest storage usage:
usage --format table --sort total --max 3 --reverse
The simplest way to use urbstat
is by downloading the executable from the
Releases page:
urbstat
for Linux x64 systems.urbstat-notls
for Linux x64 systems, compiled with TLS certificate validation disabled. Use it only if you have problems with self-signed certificates.
Download one of these files and make it executable:
chmod u+x urbstat
chmod u+x urbstat-notls
Create .env
configuration file (you can use
this example file)
and place it in the same directory with usbstat
binary. Then simply run the
application:
./urbstat --help
./urbstat-notls --help
Alternatively, you can run source file with Deno:
deno run --allow-read='.env,.env.defaults,.env.example' --allow-net=hostname:port --allow-env urbstat.js
deno run --allow-read='.env,.env.defaults,.env.example' --allow-net=hostname:port --allow-env --unsafely-ignore-certificate-errors=hostname urbstat.js
-
The default options are already set up in the
.env.defaults
file, please avoid modifying it. You can set up your own custom options in the.env
file, which you can find examples of in the.env.example
file. -
The default configuration file contains the URL and credentials that are set by the UrBackup Server installation (localhost:55414, admin, no password). You can change these by setting
URBSTAT_SERVER_URL
,URBSTAT_SERVER_USERNAME
, andURBSTAT_SERVER_PASSWORD
in the.env
file. -
Username can be specified in a configuration file or passed with
--user
option. -
Password can be specified in a configuration file or interactively at runtime when
--ask-pass
option is provided. -
Many options can also be adjusted during runtime by using command options. For more details, please refer to
urbstat <command> --help
. -
Make sure to place all configuration files in the same directory as the downloaded binary file.
You can access the documentation by using the --help option within the application.
Get general help and a list of available commands:
./urbstat --help
Get more help about a specific command and its applicable options:
./urbstat <command> --help
-h, --help - Show this help.
-V, --version - Show the version number for this program.
--user <name> - User name.
--ask-pass - Ask for connection password.
-
raw-status
Get raw response of "status" API call. Required rights:
status(all)
. Raw responses cannot be sorted, filtered, etc. Property names and values are left unaltered. -
raw-activities
Get raw response of "activities" API call. Required rights:
progress(all)
,lastacts(all)
. Raw responses cannot be sorted, filtered, etc. Property names and values are left unaltered. -
raw-usage
Get raw response of "usage" API call. Required rights:
piegraph(all)
. Raw responses cannot be sorted, filtered, etc. Property names and values are left unaltered. -
all-clients
Get all clients. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
. -
ok-clients
Get OK clients i.e. clients with OK backup status. Backups finished with issues are treated as OK by default. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
. -
failed-clients
Get failed clients i.e. clients with failed backup status or without a recent backup as configured in UrBackup Server. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
. -
stale-clients
Get stale clients i.e. clients without a recent backup as configured in urbstat. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
,URBSTAT_THRESHOLD_STALE_FILE
,URBSTAT_THRESHOLD_STALE_IMAGE
. -
void-clients
Get void clients i.e. clients not seen for a long time as configured in urbstat. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered.Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
,URBSTAT_THRESHOLD_VOID_CLIENT
. -
online-clients
Get online clients. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered.Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
. -
offline-clients
Get offline clients. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
. -
active-clients
Get currently active clients. Required rights:
status(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered.Default options are configured with:URBSTAT_CLIENTS_FORMAT
,URBSTAT_CLIENTS_SORT
,URBSTAT_LOCALE
. -
current-activities
Get current activities. Required rights:
progress(all)
,lastacts(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_ACTIVITIES_FORMAT
,URBSTAT_ACTIVITIES_SORT_CURRENT
,URBSTAT_LOCALE
. -
last-activities
Get last activities. Required rights:
progress(all)
,lastacts(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_ACTIVITIES_FORMAT
,URBSTAT_ACTIVITIES_SORT_LAST
,URBSTAT_LOCALE
. -
paused-activities
Get paused activities. Required rights:
progress(all)
,lastacts(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_ACTIVITIES_FORMAT
,URBSTAT_ACTIVITIES_SORT_CURRENT
,URBSTAT_LOCALE
. -
usage
Get storage usage. Required rights:
piegraph(all)
. If you specify "raw" format then output can not be sorted or filtered and property names/values are left unaltered. Default options are configured with:URBSTAT_USAGE_FORMAT
,URBSTAT_USAGE_SORT
,URBSTAT_LOCALE
. -
client
Get all information about one client. Required rights:
status(all)
,progress(all)
,lastacts(all)
. If you specify "raw" format then property names/values are left unaltered. Default options are configured with:URBSTAT_CLIENT_FORMAT
,URBSTAT_ACTIVITIES_SORT_CURRENT
,URBSTAT_ACTIVITIES_SORT_LAST
,URBSTAT_LOCALE
.
-
This tool implements only a subset of the UrBackup server API. It does not include methods to modify settings, add or remove clients and groups, start or stop activities, access or delete files and backups.
-
Avoid using the default
admin
account if possible. Instead, create a dedicated user through the UrBackup Server web UI and apply the principle of least privilege to that user. To get full functionality ofurbstat
, you should grant the user all rights in thestatus
,lastacts
,progress
, andpiegraph
domains. -
Deno provides granular control over permissions. To restrict what
urbstat
can access on your system and network, you can utilize theallow-read
andallow-net
flags. -
Deno rejects self-signed certificates by default. If needed, you can use the
unsafely-ignore-certificate-errors=hostname
option or supply a certificate with thecert ./ca.pem
option. -
You can use
--ask-pass
option if you don't want to put password in a configuration file. -
Make sure
.env
configuration file has strict file permissions if you put your password there. -
urbstat
binary is compiled with--unstable --allow-read='.env,.env.defaults,.env.example' --allow-net --allow-env
flags.urbstat-notls
binary is compiled with--unstable --allow-read='.env,.env.defaults,.env.example' --allow-net --allow-env --unsafely-ignore-certificate-errors
flags. -
In some scenarios you may want to download and examine the source script, set the connection details within the script, and then compile the script manually.
These third-party modules are utilized by urbstat
: