urbackup-server-api v0.9.0

node-urbackup-server-api

Node.js wrapper for UrBackup server web API.

You can use it to interact with UrBackup server installed locally or over the network. It allows you to view and modify settings, add or remove clients, get information about running tasks, clients status, backup jobs, start or stop backups and a lot more.

Please note that this code is still a work in progress - some functionality is missing, but method signatures are unlikely to change.

Installation:

npm install urbackup-server-api

Basic example to print names of clients with failed file backups:

const { UrbackupServer } = require('urbackup-server-api');

// When troubleshooting TSL connections with self-signed certificates you may try to disable certificate validation. Keep in mind that it's strongly discouraged for production use.
//process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

const server = new UrbackupServer({ url: 'http://127.0.0.1:55414', username: 'admin', password: 'secretpassword' });

(async () => {
  try {
    const allClients = await server.getStatus();
    console.log('Clients with failed file backups:');
    allClients.filter(client => client.file_ok === false).forEach(client => console.log(client.name));
  } catch (error) {
    // Deal with it
  }
})();

UrbackupServer

Represents a UrBackup Server.

Kind: global class

• UrbackupServer
  • new UrbackupServer([params])
  • .getServerIdentity() ⇒ string
  • .getUsers() ⇒ Array
  • .getGroups() ⇒ Array
  • .addGroup(params) ⇒ boolean
  • .removeGroup(params) ⇒ boolean
  • .getClients([params]) ⇒ Array
  • .addClient(params) ⇒ boolean
  • .removeClient(params) ⇒ boolean
  • .cancelRemoveClient(params) ⇒ boolean
  • .getClientHints() ⇒ Array
  • .addClientHint(params) ⇒ boolean
  • .removeClientHint(params) ⇒ boolean
  • .getClientSettings([params]) ⇒ Array
  • .setClientSettings(params) ⇒ boolean
  • .getClientAuthkey(params) ⇒ string
  • .getStatus([params]) ⇒ Array
  • .getUsage([params]) ⇒ Array
  • .getActivities([params]) ⇒ Object
  • .stopActivity(params) ⇒ boolean
  • .getBackups(params) ⇒ Object
  • .startFullFileBackup(params) ⇒ boolean
  • .startIncrementalFileBackup(params) ⇒ boolean
  • .startFullImageBackup(params) ⇒ boolean
  • .startIncrementalImageBackup(params) ⇒ boolean
  • .getLiveLog([params]) ⇒ Array
  • .getGeneralSettings() ⇒ Object
  • .setGeneralSettings(params) ⇒ boolean

new UrbackupServer(params)

Example (Connect locally to the built-in server without password)

const server = new UrbackupServer();

Example (Connect locally with password)

const server = new UrbackupServer({ url: 'http://127.0.0.1:55414', username: 'admin', password: 'secretpassword'});

Example (Connect over the network)

const server = new UrbackupServer({ url: 'https://192.168.0.2:443', username: 'admin', password: 'secretpassword'});

urbackupServer.getServerIdentity() ⇒ string

Retrieves server identity.

Kind: instance method of UrbackupServer
Returns: string - Server identity.
Example (Get server identity)

server.getServerIdentity().then(data => console.log(data));

urbackupServer.getUsers() ⇒ Array

Retrieves a list of users.

Kind: instance method of UrbackupServer
Returns: Array - Array of objects representing users. Empty array when no users found.
Example (Get all users)

server.getUsers().then(data => console.log(data));

urbackupServer.getGroups() ⇒ Array

Retrieves a list of groups. By default, UrBackup clients are added to a group id 0 with name '' (empty string).

Kind: instance method of UrbackupServer
Returns: Array - Array of objects representing groups. Empty array when no groups found.
Example (Get all groups)

server.getGroups().then(data => console.log(data));

urbackupServer.addGroup(params) ⇒ boolean

Adds a new group.

Kind: instance method of UrbackupServer
Returns: boolean - When successfull, Boolean true. Boolean false when adding was not successfull, for example group already exists.

Example (Add new group)

server.addGroup({groupName: 'prod'}).then(data => console.log(data));

urbackupServer.removeGroup(params) ⇒ boolean

Removes group. All clients in this group will be re-assigned to the default group. Using group ID should be preferred to group name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successfull, Boolean true. Boolean false when removing was not successfull. Due to UrBackup bug, it returns true when called with non-existent groupId.

Example (Remove group)

server.removeGroup({groupId: 1}).then(data => console.log(data));
server.removeGroup({groupName: 'prod'}).then(data => console.log(data));

urbackupServer.getClients(params) ⇒ Array

Retrieves a list of clients. Matches all clients by default, including clients marked for removal.

Kind: instance method of UrbackupServer
Returns: Array - Array of objects representing clients matching search criteria. Empty array when no matching clients found.

Example (Get all clients)

server.getClients().then(data => console.log(data));

Example (Get all clients, but skip clients marked for removal)

server.getClients({includeRemoved: false}).then(data => console.log(data));

Example (Get all clients belonging to a specific group)

server.getClients({groupName: 'office'}).then(data => console.log(data));

urbackupServer.addClient(params) ⇒ boolean

Adds a new client.

Kind: instance method of UrbackupServer
Returns: boolean - When successfull, Boolean true. Boolean false when adding was not successfull, for example client already exists.

Example (Add new client)

server.addClient({clientName: 'laptop2'}).then(data => console.log(data));

urbackupServer.removeClient(params) ⇒ boolean

Marks the client for removal. Actual removing happens during the cleanup in the cleanup time window. Until then, this operation can be reversed with cancelRemoveClient method. Using client ID should be preferred to client name for repeated method calls. WARNING: removing clients will also delete all their backups.

Kind: instance method of UrbackupServer
Returns: boolean - When successfull, Boolean true. Boolean false when removing was not successfull.

Example (Remove client)

server.removeClient({clientId: 1}).then(data => console.log(data));
server.removeClient({clientName: 'laptop2'}).then(data => console.log(data));

urbackupServer.cancelRemoveClient(params) ⇒ boolean

Unmarks the client as ready for removal. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successfull, Boolean true. Boolean false when stopping was not successfull.

Example (Stop the server from removing a client by ID)

server.cancelRemoveClient({clientId: 1}).then(data => console.log(data));

Example (Stop the server from removing a client by name)

server.cancelRemoveClient({clientName: 'laptop2'}).then(data => console.log(data));

urbackupServer.getClientHints() ⇒ Array

Retrieves a list of client discovery hints, also known as extra clients.

Kind: instance method of UrbackupServer
Returns: Array - Array of objects representing client hints. Empty array when no matching client hints found.
Example (Get extra clients)

server.getClientHints().then(data => console.log(data));

urbackupServer.addClientHint(params) ⇒ boolean

Adds a new client discovery hint, also known as extra client. Discovery hints are a way of improving client discovery in local area networks.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when adding was not successful.

Example (Add new extra client)

server.addClientHint({address: '192.168.100.200'}).then(data => console.log(data));

urbackupServer.removeClientHint(params) ⇒ boolean

Removes specific client discovery hint, also known as extra client.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when removing was not successful.

Example (Remove extra client)

server.removeClientHint({address: '192.168.100.200'}).then(data => console.log(data));

urbackupServer.getClientSettings(params) ⇒ Array

Retrieves client settings. Matches all clients by default, but clientId or clientName can be used to request settings for one particular client. Clients marked for removal are not excluded.

Kind: instance method of UrbackupServer
Returns: Array - Array with objects represeting client settings. Empty array when no matching client found.

Example (Get settings for all clients)

server.getClientSettings().then(data => console.log(data));

Example (Get settings for a specific client only)

server.getClientSettings({clientName: 'laptop1'}).then(data => console.log(data));
server.getClientSettings({clientId: 3}).then(data => console.log(data));

urbackupServer.setClientSettings(params) ⇒ boolean

Changes one specific element of client settings. A list of settings can be obtained with getClientSettings method. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when save request was unsuccessful or invalid key/value.

Example (Set directories to backup to be optional by default)

server.setClientSettings({clientName: 'laptop1', key: 'backup_dirs_optional', newValue: true}).then(data => console.log(data));
server.setClientSettings({clientId: 3, key: 'backup_dirs_optional', newValue: true}).then(data => console.log(data));

urbackupServer.getClientAuthkey(params) ⇒ string

Retrieves authentication key for a specified client. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: string - Client's authentication key. Empty string when no matching clients found.

Example (Get authentication key for a specific client)

server.getClientAuthkey({clientName: 'laptop1'}).then(data => console.log(data));
server.getClientAuthkey({clientId: 3}).then(data => console.log(data));

urbackupServer.getStatus(params) ⇒ Array

Retrieves backup status. Matches all clients by default, including clients marked for removal. Client name or client ID can be passed as an argument in which case only that one client's status is returned.

Kind: instance method of UrbackupServer
Returns: Array - Array of objects with status info for matching clients. Empty array when no matching clients found.

Example (Get status for all clients)

server.getStatus().then(data => console.log(data));

Example (Get status for all clients, but skip clients marked for removal)

server.getStatus({includeRemoved: false}).then(data => console.log(data));

Example (Get status for a specific client only)

server.getStatus({clientName: 'laptop1'}).then(data => console.log(data));
server.getStatus({clientId: 3}).then(data => console.log(data));

urbackupServer.getUsage(params) ⇒ Array

Retrieves storage usage. Matches all clients by default, but clientName OR clientId can be used to request usage for one particular client. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: Array - Array of objects with storage usage info for each client. Empty array when no matching clients found.

Example (Get usage for all clients)

server.getUsage().then(data => console.log(data));

Example (Get usage for a specific client only)

server.getUsage({clientName: 'laptop1'}).then(data => console.log(data));
server.getUsage({clientId: 3}).then(data => console.log(data));

urbackupServer.getActivities(params) ⇒ Object

Retrieves a list of current and/or past activities. Matches all clients by default, but clientName or clientId can be used to request activities for one particular client. By default this method returns only activities that are currently in progress and skips last activities.

Kind: instance method of UrbackupServer
Returns: Object - Object with activities info in two separate arrays (one for current and one for past activities). Object with empty arrays when no matching clients/activities found.

Example (Get current (in progress) activities for all clients)

server.getActivities().then(data => console.log(data));

Example (Get past activities for all clients)

server.getActivities({includeCurrent: false, includePast: true}).then(data => console.log(data));

Example (Get current (in progress) activities for a specific client only)

server.getActivities({clientName: 'laptop1'}).then(data => console.log(data));
server.getActivities({clientId: 3}).then(data => console.log(data));

Example (Get all activities for a specific client only)

server.getActivities({clientName: 'laptop1', includeCurrent: true, includePast: true}).then(data => console.log(data));
server.getActivities({clientId: '3', includeCurrent: true, includePast: true}).then(data => console.log(data));

urbackupServer.stopActivity(params) ⇒ boolean

Stops one activity. A list of current activities can be obtained with getActivities method. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when stopping was not successful.

Example (Stop activity)

server.stopActivity({clientName: 'laptop1', activityId: 42}).then(data => console.log(data));
server.stopActivity({clientId: 3, activityId: 42}).then(data => console.log(data));

urbackupServer.getBackups(params) ⇒ Object

Retrieves a list of file and/or image backups for a specific client. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: Object - Object with backups info. Object with empty arrays when no matching clients/backups found.

Example (Get all backups for a specific client)

server.getBackups({clientName: 'laptop1'}).then(data => console.log(data));
server.getBackups({clientId: 3}).then(data => console.log(data));

Example (Get image backups for a specific client)

server.getBackups({clientName: 'laptop1', includeFileBackups: false}).then(data => console.log(data));

Example (Get file backups for a specific client)

server.getBackups({clientName: 'laptop1', includeImageBackups: false}).then(data => console.log(data));

urbackupServer.startFullFileBackup(params) ⇒ boolean

Starts full file backup. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when starting was not successful.

Example (Start backup)

server.startFullFileBackup({clientName: 'laptop1').then(data => console.log(data));
server.startFullFileBackup({clientId: 3).then(data => console.log(data));

urbackupServer.startIncrementalFileBackup(params) ⇒ boolean

Starts incremental file backup. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when starting was not successful.

Example (Start backup)

server.startIncrementalFileBackup({clientName: 'laptop1').then(data => console.log(data));
server.startIncrementalFileBackup({clientId: 3).then(data => console.log(data));

urbackupServer.startFullImageBackup(params) ⇒ boolean

Starts full image backup. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when starting was not successful.

Example (Start backup)

server.startFullImageBackup({clientName: 'laptop1').then(data => console.log(data));
server.startFullImageBackup({clientId: 3).then(data => console.log(data));

urbackupServer.startIncrementalImageBackup(params) ⇒ boolean

Starts incremental image backup. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when starting was not successful.

Example (Start backup)

server.startIncrementalImageBackup({clientName: 'laptop1').then(data => console.log(data));
server.startIncrementalImageBackup({clientId: 3).then(data => console.log(data));

urbackupServer.getLiveLog(params) ⇒ Array

Retrieves live logs. Server logs are requested by default, but clientName or clientId can be used to request logs for one particular client. Instance property is being used internally to keep track of log entries that were previously requested. When recentOnly is set to true, then only recent (unfetched) logs are requested. Using client ID should be preferred to client name for repeated method calls.

Kind: instance method of UrbackupServer
Returns: Array - Array of objects representing log entries. Empty array when no matching clients or logs found.

Example (Get server logs)

server.getLiveLog().then(data => console.log(data));

Example (Get logs for a specific client only)

server.getLiveLog({clientName: 'laptop1'}).then(data => console.log(data));
server.getLiveLog({clientId: 3}).then(data => console.log(data));

Example (Get logs for a specific client only, but skip previously fetched logs)

server.getLiveLog({clientName: 'laptop1', recentOnly: true}).then(data => console.log(data));

urbackupServer.getGeneralSettings() ⇒ Object

Retrieves general settings.

Kind: instance method of UrbackupServer
Returns: Object - Object with general settings.
Example (Get general settings)

server.getGeneralSettings().then(data => console.log(data));

urbackupServer.setGeneralSettings(params) ⇒ boolean

Changes one specific element of general settings. A list of settings can be obtained with getGeneralSettings method.

Kind: instance method of UrbackupServer
Returns: boolean - When successful, Boolean true. Boolean false when save request was unsuccessful or invalid key/value.

Example (Disable image backups)

server.setGeneralSettings({key: 'no_images', newValue: true}).then(data => console.log(data));