Skip to content
/ node-urbackup-server-api Public

Node.js wrapper for UrBackup Server web API.

License

MIT license
2 stars 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

bartmichu/node-urbackup-server-api

BranchesTags

Repository files navigation

node-urbackup-server-api

This module provides a Node.js interface for interacting with the UrBackup server's web API, whether the server is installed locally or accessed over a network. It facilitates the management and monitoring of backup operations by offering a range of functionalities, including:

  • Viewing and modifying server settings
  • Viewing and modifying client settings
  • Adding or removing clients
  • Managing groups
  • Retrieving information about running tasks and client statuses
  • Managing backup jobs, including starting and stopping backups
  • Accessing live logs
  • Fetching backup history and details for specific clients

The module aims to simplify the integration of UrBackup server management into Node.js applications, making it easier to automate and control backup operations programmatically.

Please note that this module is still in a pre-1.0.0 release. Some functionality is missing. All implemented methods are working and considered stable, but public method signatures occasionally change. Always check the changelog before updating to understand any potential breaking changes.

Requirements

To use this module, ensure you have the following:

Installation

To install the module, use npm:

npm install urbackup-server-api

Usage Example

Here's a basic example to get you started:

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 {
    // Check if server is currently busy
    const activities = await urbackup.getCurrentActivities();
    console.log(`Busy: ${activities.length > 0}`);

    // Get a list of production clients
    const prodClients = await urbackup.getGroupMembers({ groupName: 'prod' }).then(data => console.log(data));

    // Get production clients with failed image backup
    const failedClients = await urbackup.getFailedClients({ groupName: 'prod', includeFileBackups: false }).then(data => console.log(data));

    // Get all clients without both file and image backups
   const blankClients = await urbackup.getBlankClients().then(data => console.log(data));

  } catch (error) {
    // Deal with it
  }
})();

Example implementation

https://github.com/bartmichu/urbstat/

urbstat

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.

CHANGELOG

This changelog starts at version 0.20.0 and includes a selection of significant changes.

Breaking Changes

  • 0.50.0

    • Reverted property name changes introduced in 0.40.0 - this was not a good idea. If such a change is needed in the future, it will be an optional feature (disabled by default) controlled by a method parameter.

  • 0.40.0

    • Breaking change of property names of objects returned by getClients() method. This affects the getClients(), getGroupMembers(), and getRemovedClients() methods.

  • 0.30.0

    • Breaking change of naming in getActivities() method: previously, it used the past property, which is now renamed to last. Similarly, the includePast parameter has been renamed to includeLast.

Notable Changes

  • 0.53.0

    • Fixed the getBlankClients() method: image backups were not being matched correctly.

  • 0.52.0

    • Added following methods: getOutdatedClients(), getConflictingClients(), removeUser(), addUser(), isServerOutdated().

  • 0.51.0

    • Added following methods: getFailedClients(), getOkClients().
    • Added following parameters to getBlankClients(): includeFileBackups, includeImageBackups, groupName.
    • Added groupName parameter to the following methods: getRemovedClients(), getOnlineClients(), getOfflineClients(), getActiveClients(), getBlankClients().

  • 0.50.0

    • Reverted property name changes introduced in 0.40.0 - this was not a good idea. If such a change is needed in the future, it will be an optional feature (disabled by default) controlled by a method parameter.

  • 0.42.0

    • Added following methods: getServerVersion(), getUserRights(), getRawStatus(), getRawUsage(), getRawProgress(), getActiveClients(), getBlankClients().
    • Added following properties to objects returned by getClients() method: status, seen, processes, imageBackupDisabled, imageBackupOk, lastImageBackup, fileBackupOk, lastFileBackup, lastFileBackupIssues.

  • 0.41.0

    • Added following properties to objects returned by getClients() method: online, uid, ip, clientVersion, osFamily, osVersion. This affects the getClients(), getGroupMembers(), getRemovedClients(), getOnlineClients(), getOfflineClients().

  • 0.40.0

    • Breaking change of property names of objects returned by getClients() method. This affects the getClients(), getGroupMembers(), and getRemovedClients() methods.

  • 0.31.0

    • Added following methods: getOnlineClients(), getOfflineClients(), getRemovedClients(), getPausedActivities().

  • 0.30.0

    • Breaking change of naming in getActivities() method: previously, it used the past property, which is now renamed to last. Similarly, the includePast parameter has been renamed to includeLast.
    • Defaults change for getActivities() method: previously, it returned only current activities by default. Now, both current and last activities are included.

  • 0.22.0

    • Added following methods: getCurrentActivities(), getPastActivities(), getMailSettings(), getLdapSettings().

  • 0.21.0

    • Added getGroupMembers() method.

  • 0.20.1

    • Fixed getClientAuthKey() method. Previously, due to changes introduced by a UrBackup Server update, it was always returning an empty string.

  • 0.20.0

    • Fixed returned type inconsistencies for the following methods: getClientId(), getClientName(), getGroupId(), getGroupName().

Below is an automatically generated reference from JSDoc.

UrbackupServer

Represents a UrBackup Server.

Kind: global class

new UrbackupServer([params])

This is a constructor.

Param Type Default Description
[params] object An optional object containing parameters.
[params.url] string "'http://127.0.0.1:55414'" The URL of the server, must include the protocol, hostname, and port. Defaults to http://127.0.0.1:55414.
[params.username] string "''" The username used for logging in. If empty, anonymous login method will be used. Defaults to an empty string.
[params.password] string "''" The password used to log in. Defaults to an empty string.

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

const server = new UrbackupServer();

Example (Connect locally with a specified 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() ⇒ Promise.<string>

Retrieves server identity.

Kind: instance method of UrbackupServer
Returns: Promise.<string> - The server identity.
Throws:

  • Error If the API response is missing required values or if the login fails.

Example (Get server identity)

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

urbackupServer.getServerVersion() ⇒ Promise.<object>

Retrieves the server version in both number and string representation.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - An object containing the server version number and string.
Throws:

  • Error If the API response is missing required values or if the login fails.

Example (Get server version number)

server.getServerVersion().then(data => console.log(data.number));

Example (Get server version string)

server.getServerVersion().then(data => console.log(data.string));

urbackupServer.isServerOutdated() ⇒ Promise.<boolean>

Checks if the server version is outdated compared to the available version.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the server version is outdated, false otherwise.
Throws:

  • Error If the API response is missing required values or if the login fails.

Example

server.isServerOutdated().then(isOutdated => console.log(isOutdated));

urbackupServer.getUsers() ⇒ Promise.<Array.<object>>

Retrieves a list of users.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing users. If no users are found, it returns an empty array.
Throws:

  • Error If the login fails or the API response is missing expected values.

Example (Get all users)

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

urbackupServer.addUser(params) ⇒ Promise.<boolean>

Adds a new user with the specified username, password, and rights.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the user was added successfully, false otherwise.
Throws:

  • Error If required parameters are missing, the login fails, or the API response is missing expected values.
Param Type Default Description
params object An object containing parameters.
params.userName string The username for the new user.
params.password string The password for the new user.
[params.isAdmin] boolean false Whether the new user should have admin rights (all domains, all rights). Defaults to false.
[params.rights] Array.<object> Array of user permissions. Ignored if isAdmin is true. Defaults to the default user rights.

Example (Add a regular user)

server.addUser({ userName: 'newUser', password: 'userPassword' }).then(result => console.log(result));

Example (Add an admin user)

server.addUser({ userName: 'adminUser', password: 'adminPassword', isAdmin: true }).then(result => console.log(result));

urbackupServer.removeUser(params) ⇒ Promise.<boolean>

Removes a user by their user ID.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to a boolean indicating whether the user was successfully removed.
Throws:

  • Error If the userId parameter is missing or invalid, or if the login fails.
Param Type Description
params object An object containing parameters.
params.userId number The ID of the user to be removed.

Example (Remove a user by their ID)

server.removeUser({ userId: 123 }).then(status => console.log(status));

urbackupServer.getUserRights([params]) ⇒ Promise.<(Array|null)>

Retrieves the rights of a specific user.

Kind: instance method of UrbackupServer
Returns: Promise.<(Array|null)> - A promise that resolves to an array of user rights, or null if the user is not found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.userId] string The user's ID. Takes precedence if both userId and userName are defined. Required if clientName is undefined.
[params.userName] string "this.#username" The user's name. Ignored if userId is defined. Defaults to the username of the current session. Required if clientId is undefined.

Example (Get user rights of the current session user)

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

Example (Get user rights by user ID)

server.getUserRights({ userId: '12345' }).then(data => console.log(data));

Example (Get user rights by user name)

server.getUserRights({ userName: 'john_doe' }).then(data => console.log(data));

urbackupServer.getGroups() ⇒ Promise.<Array.<object>>

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

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing groups. If no groups are found, it returns an empty array.
Throws:

  • Error If the login fails or the API response is missing expected values.

Example (Get all groups)

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

urbackupServer.addGroup(params) ⇒ Promise.<boolean>

Adds a new group.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. If the group already exists, or adding the group was not successful for any reason, returns false.
Throws:

  • Error If the groupName is missing or invalid, or if the API response is missing expected values.
Param Type Description
params object An object containing parameters.
params.groupName string The group name. Must be unique and cannot be an empty string.

Example (Add new group)

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

urbackupServer.removeGroup(params) ⇒ Promise.<boolean>

Removes a group. All clients in this group will be reassigned to the default group. Does not allow removal of the default group (ID: 0, name: '').

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When the removal is successful, the method returns true. If the removal is not successful, the method returns false.
Throws:

  • Error If both groupId and groupName are missing or invalid, or if the login fails.
Param Type Description
params object An object containing parameters.
[params.groupId] number Group ID. Must be greater than 0. Takes precedence if both groupId and groupName are defined. Required if groupName is undefined.
[params.groupName] string Group name. Must be different than '' (empty string). Ignored if both groupId and groupName are defined. Required if groupId is undefined.

Example (Remove group)

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

urbackupServer.getGroupMembers(params) ⇒ Promise.<Array.<object>>

Retrieves a list of clients who are members of a given group. This is only a convenience method that wraps the getClients() method.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients matching the search criteria. Returns an empty array when no matching clients are found.
Throws:

  • Error If both groupId and groupName are missing or invalid.
Param Type Description
params object An object containing parameters.
[params.groupId] number Group ID. Ignored if both groupId and groupName are defined. Required if groupName is undefined.
[params.groupName] string Group name. Takes precedence if both groupId and groupName are defined. Required if groupId is undefined.

Example (Get members of default group)

server.getGroupMembers({ groupId: 0 }).then(data => console.log(data));

Example (Get all clients belonging to a specific group)

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

urbackupServer.getClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of clients. By default, this method matches all clients, including those marked for removal.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients matching the search criteria. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

Example (Get all clients)

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

Example (Get all clients, but exclude 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.getRemovedClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of clients marked for removal.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.

Example (Get clients marked for removal)

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

Example (Get clients marked for removal in a specific group)

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

urbackupServer.getOnlineClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of online clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

Example (Get all online clients)

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

Example (Get online clients from a specific group)

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

urbackupServer.getOfflineClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of offline clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

Example (Get all offline clients)

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

Example (Get offline clients, skip clients marked for removal)

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

Example (Get offline clients from a specific groups)

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

urbackupServer.getActiveClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of active clients.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

Example (Get all active clients)

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

urbackupServer.getBlankClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of blank clients, i.e., clients without any finished file and/or image backups. By default, it matches clients without both file and image backups.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.
[params.includeFileBackups] boolean true Whether or not file backups should be taken into account when matching clients. Defaults to true.
[params.includeImageBackups] boolean true Whether or not image backups should be taken into account when matching clients. Defaults to true.

Example (Get all blank clients, i.e., clients without both file and image backups)

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

Example (Get blank clients, skip clients marked for removal)

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

Example (Get clients without any file backups)

server.getBlankClients({ includeImageBackups: false }).then(data => console.log(data));

Example (Get clients without any image backups)

server.getBlankClients({ includeFileBackups: false }).then(data => console.log(data));

urbackupServer.getFailedClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of failed clients, i.e., clients with failed backup status.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.
[params.includeFileBackups] boolean true Whether or not file backups should be taken into account when matching clients. Defaults to true.
[params.includeImageBackups] boolean true Whether or not image backups should be taken into account when matching clients. Defaults to true.
[params.includeBlankClients] boolean true Whether or not blank clients should be taken into account when matching clients. Defaults to true.
[params.failOnFileIssues] boolean false Whether or not to treat file backups finished with issues as being failed. Defaults to false.

Example (Get clients with failed file or image backups)

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

Example (Get failed clients, skip clients marked for removal)

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

Example (Get clients with failed file backups)

server.getFailedClients({ includeImageBackups: false }).then(data => console.log(data));

Example (Get clients with failed image backups)

server.getFailedClients({ includeFileBackups: false }).then(data => console.log(data));

urbackupServer.getOkClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of OK clients, i.e., clients with OK backup status. File backups finished with issues are treated as OK by default.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.
[params.includeFileBackups] boolean true Whether or not file backups should be taken into account when matching clients. Defaults to true.
[params.includeImageBackups] boolean true Whether or not image backups should be taken into account when matching clients. Defaults to true.
[params.failOnFileIssues] boolean false Whether or not to treat file backups finished with issues as being failed. Defaults to false.

Example (Get OK clients, use default parameters)

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

Example (Get OK clients, skip clients marked for removal)

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

Example (Get clients with OK file backup, skip image backup status)

server.getOkClients({ includeImageBackups: false }).then(data => console.log(data));

Example (Get clients with OK file backup but treat backup issues as a failure, skip image backup status)

server.getOkClients({ includeImageBackups: false, failOnFileIssues: true }).then(data => console.log(data));

urbackupServer.getOutdatedClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of clients using an outdated version.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.groupName] string Group name. Defaults to undefined, which matches all groups.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

Example (Get all outdated clients)

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

Example (Get outdated clients in a specific group)

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

Example (Get outdated clients, exclude clients marked for removal)

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

urbackupServer.getConflictingClients([params]) ⇒ Promise.<Array.<object>>

Retrieves a list of online clients with the same, i.e., conflicting IP address.

Kind: instance method of UrbackupServer
Returns: Promise.<Array.<object>> - A promise that resolves to an array of objects representing clients. Returns an empty array when no matching clients are found.
Throws:

  • Error If the login fails or the API response is missing expected values.
Param Type Default Description
[params] object An optional object containing parameters.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

Example (Get all online clients with conflicting IP addresses)

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

Example (Get online clients with conflicting IP addresses, exclude clients marked for removal)

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

urbackupServer.addClient(params) ⇒ Promise.<boolean>

Adds a new client.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. If adding the client was not successful, for example if the client already exists, returns false.
Throws:

  • Error If the clientName is missing or invalid, if the login fails, or if the API response is missing expected values.
Param Type Description
params object An object containing parameters.
params.clientName string The client's name.

Example (Add new client)

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

urbackupServer.removeClient(params) ⇒ Promise.<boolean>

Marks the client for removal. Actual removal occurs during the cleanup time window. Until then, this operation can be reversed with the cancelRemoveClient method. WARNING: Removing clients will also delete all their backups stored on the UrBackup server.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false if the removal was not successful.
Throws:

  • Error If parameters are missing or invalid.
Param Type Description
params object An object containing parameters.
[params.clientId] number Client's ID. If both clientId and clientName are defined, the ID takes precedence. Required if clientName is undefined.
[params.clientName] string Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

Example (Remove client by ID)

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

Example (Remove client by name)

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

urbackupServer.cancelRemoveClient(params) ⇒ Promise.<boolean>

Unmarks the client as ready for removal.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false if the stopping process was not successful.
Throws:

  • Error If parameters are missing or invalid.
Param Type Description
params object An object containing parameters.
[params.clientId] number Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

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() ⇒ Promise.<Array>

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

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - Array of objects representing client hints. Returns an empty array when no matching client hints are found.
Throws:

  • Error If the login fails or the API response is incorrect.

Example (Get extra clients)

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

urbackupServer.addClientHint(params) ⇒ Promise.<boolean>

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

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false when adding was not successful.
Throws:

  • Error If parameters are missing or invalid, or if the API response is incorrect.
Param Type Description
params object An object containing parameters.
params.address string Client's IP address or hostname.

Example (Add new extra client)

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

urbackupServer.removeClientHint(params) ⇒ Promise.<boolean>

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

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false when removing was not successful.
Throws:

  • Error If parameters are missing or invalid, or if the API response is incorrect.
Param Type Description
params object An object containing parameters.
params.address string Client's IP address or hostname.

Example (Remove extra client)

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

urbackupServer.getClientSettings([params]) ⇒ Promise.<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 from the results.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - An array with objects representing client settings. Returns an empty array if no matching client is found.
Throws:

  • Error If parameters are missing or invalid, or if the API response is incorrect.
Param Type Description
[params] object An optional object containing parameters.
[params.clientId] number Client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientName is also undefined.
[params.clientName] string Client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.

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) ⇒ Promise.<boolean>

Changes one specific element of client settings. A list of settings can be obtained with the getClientSettings method.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - When successful, returns true. Returns false when the save request was unsuccessful or if the key/value is invalid.
Throws:

  • Error If parameters are missing or invalid, or if the API response is incorrect.
Param Type Description
params object An object containing parameters.
[params.clientId] number Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.
params.key string Settings element to change.
params.newValue string | number | boolean New value for settings element.

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) ⇒ Promise.<string>

Retrieves the authentication key for a specified client.

Kind: instance method of UrbackupServer
Returns: Promise.<string> - Client's authentication key. Returns an empty string if no matching clients are found.
Throws:

  • Error If parameters are missing or invalid, or if the API response is incorrect.
Param Type Description
params object An object containing parameters.
[params.clientId] number Client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string Client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

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]) ⇒ Promise.<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: Promise.<Array> - Array of objects with status info for matching clients. Returns an empty array if no matching clients are found.
Throws:

  • Error If the API response is incorrect or if login fails.
Param Type Default Description
[params] object An object containing parameters.
[params.clientId] number Client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.
[params.clientName] string Client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientName is also undefined.
[params.includeRemoved] boolean true Whether or not clients pending deletion should be included. Defaults to true.

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]) ⇒ Promise.<Array>

Retrieves storage usage. By default, it matches all clients, but you can use clientName or clientId to request usage for one particular client.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - A promise that resolves to an array of objects with storage usage info for each client. Resolves to an empty array if no matching clients are found.
Throws:

  • Error If the API response is missing values or if login fails.
Param Type Description
[params] object An optional object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientName is also undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.

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]) ⇒ Promise.<object>

Retrieves a list of current and/or last 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 both current and last activities.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - An object with activities info in two separate arrays (one for current and one for last activities). Returns an object with empty arrays when no matching clients/activities are found.
Throws:

  • Error If the API response is missing values or if login fails.
Param Type Default Description
[params] object An optional object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.
[params.includeCurrent] boolean true Whether or not currently running activities should be included. Defaults to true.
[params.includeLast] boolean true Whether or not last activities should be included. Defaults to true.

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

server.getActivities({ includeLast: false }).then(data => console.log(data));

Example (Get last activities for all clients)

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

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

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

Example (Get all activities for a specific client only)

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

urbackupServer.getCurrentActivities([params]) ⇒ Promise.<Array>

Retrieves a list of current (in progress) activities. This is only a convenience method that wraps the getActivities() method. Matches all clients by default, but clientName or clientId can be used to request activities for one particular client.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - A promise that resolves to an array of current activities. Returns an empty array when no matching clients/activities are found.
Throws:

  • Error If the API response is missing values or if login fails.
Param Type Description
[params] object An optional object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.

Example (Get current activities for all clients)

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

Example (Get current activities for a specific client only)

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

urbackupServer.getLastActivities([params]) ⇒ Promise.<Array>

Retrieves a list of last activities. This is only a convenience method that wraps the getActivities() method. Matches all clients by default, but clientName or clientId can be used to request activities for one particular client.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - A promise that resolves to an array of last activities. Returns an empty array when no matching clients/activities are found.
Throws:

  • Error If the API response is missing values or if login fails.
Param Type Description
[params] object An optional object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.

Example (Get last activities for all clients)

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

Example (Get last activities for a specific client only)

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

urbackupServer.getPausedActivities([params]) ⇒ Promise.<Array>

Retrieves a list of paused activities. Matches all clients by default, but clientName or clientId can be used to request paused activities for a particular client.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - A promise that resolves to an array of paused activities. Returns an empty array when no matching clients/activities are found.
Throws:

  • Error If the API response is missing values or if login fails.
Param Type Description
[params] object An optional object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which matches all clients if clientId is also undefined.

Example (Get all paused activities)

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

Example (Get paused activities for a specific client only)

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

urbackupServer.stopActivity(params) ⇒ Promise.<boolean>

Stops one selected activity. A list of current activities can be obtained with the getActivities method.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the activity was stopped successfully, or false if stopping was not successful.
Throws:

  • Error If there are missing or invalid parameters, if the API response is missing values, or if login fails.
Param Type Description
params object An object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.
params.activityId number The activity ID. Required.

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) ⇒ Promise.<object>

Retrieves a list of file and/or image backups for a specific client.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to an object with backups info in two separate arrays (one for file and one for image backups). Returns an object with empty arrays when no matching clients/backups are found.
Throws:

  • Error If there are missing or invalid parameters, if the API response is missing values, or if login fails.
Param Type Default Description
params object An object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.
[params.includeFileBackups] boolean true Whether or not file backups should be included. Defaults to true.
[params.includeImageBackups] boolean true Whether or not image backups should be included. Defaults to true.

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) ⇒ Promise.<boolean>

Starts a full file backup.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the backup job was started successfully, or false if starting was not successful.
Throws:

  • Error If there are missing or invalid parameters.
Param Type Description
params object An object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

Example (Start a full file backup by client name)

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

Example (Start a full file backup by client ID)

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

urbackupServer.startIncrementalFileBackup(params) ⇒ Promise.<boolean>

Starts an incremental file backup.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the backup job was started successfully, or false if starting was not successful.
Throws:

  • Error If there are missing or invalid parameters.
Param Type Description
params object An object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

Example (Start an incremental file backup by client name)

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

Example (Start an incremental file backup by client ID)

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

urbackupServer.startFullImageBackup(params) ⇒ Promise.<boolean>

Starts a full image backup.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the backup job was started successfully, or false if starting was not successful.
Throws:

  • Error If there are missing or invalid parameters.
Param Type Description
params object An object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

Example (Start a full image backup by client name)

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

Example (Start a full image backup by client ID)

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

urbackupServer.startIncrementalImageBackup(params) ⇒ Promise.<boolean>

Starts an incremental image backup.

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true if the backup job was started successfully, or false if starting was not successful.
Throws:

  • Error If there are missing or invalid parameters.
Param Type Description
params object An object containing parameters.
[params.clientId] number The client's ID. Takes precedence if both clientId and clientName are defined. Required if clientName is undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Required if clientId is undefined.

Example (Start an incremental image backup by client name)

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

Example (Start an incremental image backup by client ID)

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

urbackupServer.getLiveLog([params]) ⇒ Promise.<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 used internally to keep track of log entries that were previously requested. When recentOnly is set to true, only recent (unfetched) logs are requested.

Kind: instance method of UrbackupServer
Returns: Promise.<Array> - A promise that resolves to an array of objects representing log entries. Returns an empty array when no matching clients or logs are found.
Throws:

  • Error If there is an API response error or login failure.
Param Type Default Description
[params] object An optional object containing parameters.
[params.clientId] number The client's ID. Must be greater than zero. Takes precedence if both clientId and clientName are defined. Defaults to undefined, which means server logs will be requested if clientId is also undefined.
[params.clientName] string The client's name. Ignored if both clientId and clientName are defined. Defaults to undefined, which means server logs will be requested if clientName is also undefined.
[params.recentOnly] boolean false Whether only recent (unfetched) entries should be requested. Defaults to false.

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() ⇒ Promise.<object>

Retrieves general settings.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to an object with general settings.
Throws:

  • Error If there is an API response error or login failure.

Example (Get general settings)

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

urbackupServer.getMailSettings() ⇒ Promise.<object>

Retrieves mail settings.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to an object with mail settings.
Throws:

  • Error If there is an API response error or login failure.

Example (Get mail settings)

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

urbackupServer.getLdapSettings() ⇒ Promise.<object>

Retrieves LDAP settings.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to an object with LDAP settings.
Throws:

  • Error If there is an API response error or login failure.

Example (Get LDAP settings)

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

urbackupServer.setGeneralSettings(params) ⇒ Promise.<boolean>

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

Kind: instance method of UrbackupServer
Returns: Promise.<boolean> - A promise that resolves to true when the settings change is successful, and false if the save request was unsuccessful or the key/value is invalid.
Throws:

  • Error If there is a syntax error, API response error, or login failure.
Param Type Description
params object An object containing parameters.
params.key string The settings element to change.
params.newValue string | number | boolean The new value for the settings element.

Example (Disable image backups)

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

urbackupServer.getRawStatus() ⇒ Promise.<object>

Retrieves the raw response from the 'status' API call. Property names and values are left unaltered.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to the raw status response object.
Throws:

  • Error If the login fails.

Example

urbackup.getRawStatus().then(data => console.log(data));

urbackupServer.getRawUsage() ⇒ Promise.<object>

Retrieves the raw response from the 'usage' API call. Property names and values are left unaltered.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to the raw usage response object.
Throws:

  • Error If the login fails.

Example

const data = await urbackup.getRawUsage();

urbackupServer.getRawProgress() ⇒ Promise.<object>

Retrieves the raw response from the 'progress' API call. Property names and values are left unaltered.

Kind: instance method of UrbackupServer
Returns: Promise.<object> - A promise that resolves to the raw progress response object.
Throws:

  • Error If the login fails.

Example

const data = await urbackup.getRawProgress();

About

Node.js wrapper for UrBackup Server web API.

Topics

nodejs javascript urbackup

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

2 watching

Forks

2 forks
Report repository

Languages