# 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, and method signatures may change without notice. Always review the [CHANGELOG](https://github.com/bartmichu/node-urbackup-server-api/blob/main/CHANGELOG.md) before updating to understand any potential breaking changes._ ## Requirements To use this module, ensure you have the following: - An Active LTS or Maintenance LTS version of Node.js (https://nodejs.org/en/about/previous-releases) - A current release of the UrBackup Server ## Installation To install the module, use npm: ```shell npm install urbackup-server-api ``` ## Usage Example Here's a basic example to get you started: ```javascript import { UrbackupServer } from '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 **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. --- ## Below is an automatically generated reference from JSDoc. ## UrbackupServer Represents a UrBackup Server. **Kind**: global class - [UrbackupServer](#UrbackupServer) - [new UrbackupServer([params])](#new_UrbackupServer_new) - [.getServerIdentity()](#UrbackupServer+getServerIdentity) ⇒ Promise.<string> - [.getServerVersion()](#UrbackupServer+getServerVersion) ⇒ Promise.<object> - [.isServerOutdated()](#UrbackupServer+isServerOutdated) ⇒ Promise.<boolean> - [.getUsers()](#UrbackupServer+getUsers) ⇒ Promise.<Array.<object>> - [.addUser(params)](#UrbackupServer+addUser) ⇒ Promise.<boolean> - [.removeUser(params)](#UrbackupServer+removeUser) ⇒ Promise.<boolean> - [.getUserRights([params])](#UrbackupServer+getUserRights) ⇒ Promise.<(Array\|null)> - [.getGroups()](#UrbackupServer+getGroups) ⇒ Promise.<Array.<object>> - [.addGroup(params)](#UrbackupServer+addGroup) ⇒ Promise.<boolean> - [.removeGroup(params)](#UrbackupServer+removeGroup) ⇒ Promise.<boolean> - [.getGroupMembers(params)](#UrbackupServer+getGroupMembers) ⇒ Promise.<Array.<object>> - [.getClients([params])](#UrbackupServer+getClients) ⇒ Promise.<Array.<object>> - [.getRemovedClients([params])](#UrbackupServer+getRemovedClients) ⇒ Promise.<Array.<object>> - [.getOnlineClients([params])](#UrbackupServer+getOnlineClients) ⇒ Promise.<Array.<object>> - [.getOfflineClients([params])](#UrbackupServer+getOfflineClients) ⇒ Promise.<Array.<object>> - [.getActiveClients([params])](#UrbackupServer+getActiveClients) ⇒ Promise.<Array.<object>> - [.getBlankClients([params])](#UrbackupServer+getBlankClients) ⇒ Promise.<Array.<object>> - [.getFailedClients([params])](#UrbackupServer+getFailedClients) ⇒ Promise.<Array.<object>> - [.getOkClients([params])](#UrbackupServer+getOkClients) ⇒ Promise.<Array.<object>> - [.getOutdatedClients([params])](#UrbackupServer+getOutdatedClients) ⇒ Promise.<Array.<object>> - [.getConflictingClients([params])](#UrbackupServer+getConflictingClients) ⇒ Promise.<Array.<object>> - [.getUnseenClients([params])](#UrbackupServer+getUnseenClients) ⇒ Promise.<Array.<object>> - [.getStaleClients([params])](#UrbackupServer+getStaleClients) ⇒ Promise.<Array> - [.addClient(params)](#UrbackupServer+addClient) ⇒ Promise.<boolean> - [.removeClient(params)](#UrbackupServer+removeClient) ⇒ Promise.<boolean> - [.cancelRemoveClient(params)](#UrbackupServer+cancelRemoveClient) ⇒ Promise.<boolean> - [.getClientHints()](#UrbackupServer+getClientHints) ⇒ Promise.<Array> - [.addClientHint(params)](#UrbackupServer+addClientHint) ⇒ Promise.<boolean> - [.removeClientHint(params)](#UrbackupServer+removeClientHint) ⇒ Promise.<boolean> - [.getClientSettings([params])](#UrbackupServer+getClientSettings) ⇒ Promise.<Array> - [.setClientSettings(params)](#UrbackupServer+setClientSettings) ⇒ Promise.<boolean> - [.getClientGroup(params)](#UrbackupServer+getClientGroup) ⇒ Promise.<(object\|null)> - [.setClientGroup(params)](#UrbackupServer+setClientGroup) ⇒ Promise.<boolean> - [.getClientAuthkey(params)](#UrbackupServer+getClientAuthkey) ⇒ Promise.<string> - [.getStatus([params])](#UrbackupServer+getStatus) ⇒ Promise.<Array> - [.getUsage([params])](#UrbackupServer+getUsage) ⇒ Promise.<Array> - [.getActivities([params])](#UrbackupServer+getActivities) ⇒ Promise.<object> - [.getCurrentActivities([params])](#UrbackupServer+getCurrentActivities) ⇒ Promise.<Array> - [.getLastActivities([params])](#UrbackupServer+getLastActivities) ⇒ Promise.<Array> - [.getPausedActivities([params])](#UrbackupServer+getPausedActivities) ⇒ Promise.<Array> - [.stopActivity(params)](#UrbackupServer+stopActivity) ⇒ Promise.<boolean> - [.getBackups(params)](#UrbackupServer+getBackups) ⇒ Promise.<object> - [.startFullFileBackup(params)](#UrbackupServer+startFullFileBackup) ⇒ Promise.<boolean> - [.startIncrementalFileBackup(params)](#UrbackupServer+startIncrementalFileBackup) ⇒ Promise.<boolean> - [.startFullImageBackup(params)](#UrbackupServer+startFullImageBackup) ⇒ Promise.<boolean> - [.startIncrementalImageBackup(params)](#UrbackupServer+startIncrementalImageBackup) ⇒ Promise.<boolean> - [.getLiveLog([params])](#UrbackupServer+getLiveLog) ⇒ Promise.<Array> - [.getGeneralSettings()](#UrbackupServer+getGeneralSettings) ⇒ Promise.<object> - [.getMailSettings()](#UrbackupServer+getMailSettings) ⇒ Promise.<object> - [.getLdapSettings()](#UrbackupServer+getLdapSettings) ⇒ Promise.<object> - [.setGeneralSettings(params)](#UrbackupServer+setGeneralSettings) ⇒ Promise.<boolean> - [.getRawStatus()](#UrbackupServer+getRawStatus) ⇒ Promise.<object> - [.getRawUsage()](#UrbackupServer+getRawUsage) ⇒ Promise.<object> - [.getRawProgress()](#UrbackupServer+getRawProgress) ⇒ Promise.<object> ### 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)_ ```js const server = new UrbackupServer(); ``` **Example** _(Connect locally with a specified password)_ ```js const server = new UrbackupServer({ url: 'http://127.0.0.1:55414', username: 'admin', password: 'secretpassword', }); ``` **Example** _(Connect over the network)_ ```js 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](#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)_ ```js 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](#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)_ ```js server.getServerVersion().then((data) => console.log(data.number)); ``` **Example** _(Get server version string)_ ```js 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](#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** ```js server.isServerOutdated().then((isOutdated) => console.log(isOutdated)); ``` ### urbackupServer.getUsers() ⇒ Promise.<Array.<object>> Retrieves a list of users. **Kind**: instance method of [UrbackupServer](#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)_ ```js 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](#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)_ ```js server .addUser({ userName: 'newUser', password: 'userPassword' }) .then((result) => console.log(result)); ``` **Example** _(Add an admin user)_ ```js 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](#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)_ ```js 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](#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)_ ```js server.getUserRights().then((data) => console.log(data)); ``` **Example** _(Get user rights by user ID)_ ```js server.getUserRights({ userId: '12345' }).then((data) => console.log(data)); ``` **Example** _(Get user rights by user name)_ ```js 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](#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)_ ```js server.getGroups().then((data) => console.log(data)); ``` ### urbackupServer.addGroup(params) ⇒ Promise.<boolean> Adds a new group. **Kind**: instance method of [UrbackupServer](#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)_ ```js 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](#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)_ ```js 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](#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. Takes precedence if both `groupId` and `groupName` are defined. Required if `groupName` is undefined. | | params.groupName | string | Group name. Ignored if both `groupId` and `groupName` are defined. Required if `groupId` is undefined. | **Example** _(Get members of default group)_ ```js server.getGroupMembers({ groupId: 0 }).then((data) => console.log(data)); ``` **Example** _(Get all clients belonging to a specific group)_ ```js 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](#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)_ ```js server.getClients().then((data) => console.log(data)); ``` **Example** _(Get all clients, but exclude clients marked for removal)_ ```js server.getClients({ includeRemoved: false }).then((data) => console.log(data)); ``` **Example** _(Get all clients belonging to a specific group)_ ```js 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](#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)_ ```js server.getRemovedClients().then((data) => console.log(data)); ``` **Example** _(Get clients marked for removal in a specific group)_ ```js 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](#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.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. | **Example** _(Get all online clients)_ ```js server.getOnlineClients().then((data) => console.log(data)); ``` **Example** _(Get online clients from a specific group)_ ```js 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](#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.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. | **Example** _(Get all offline clients)_ ```js server.getOfflineClients().then((data) => console.log(data)); ``` **Example** _(Get offline clients, skip clients marked for removal)_ ```js server .getOfflineClients({ includeRemoved: false }) .then((data) => console.log(data)); ``` **Example** _(Get offline clients from a specific groups)_ ```js 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](#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)_ ```js 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. Matching empty clients considers whether file backups or image backups are enabled. By default, it matches clients without both file and image backups. **Kind**: instance method of [UrbackupServer](#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)_ ```js server.getBlankClients().then((data) => console.log(data)); ``` **Example** _(Get blank clients, skip clients marked for removal)_ ```js server .getBlankClients({ includeRemoved: false }) .then((data) => console.log(data)); ``` **Example** _(Get clients without any file backups)_ ```js server .getBlankClients({ includeImageBackups: false }) .then((data) => console.log(data)); ``` **Example** _(Get clients without any image backups)_ ```js 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](#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.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. 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 clients with failed file or image backups)_ ```js server.getFailedClients().then((data) => console.log(data)); ``` **Example** _(Get failed clients, skip clients marked for removal)_ ```js server .getFailedClients({ includeRemoved: false }) .then((data) => console.log(data)); ``` **Example** _(Get clients with failed file backups)_ ```js server .getFailedClients({ includeImageBackups: false }) .then((data) => console.log(data)); ``` **Example** _(Get clients with failed image backups)_ ```js 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](#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)_ ```js server.getOkClients().then((data) => console.log(data)); ``` **Example** _(Get OK clients, skip clients marked for removal)_ ```js server .getOkClients({ includeRemoved: false }) .then((data) => console.log(data)); ``` **Example** _(Get clients with OK file backup, skip image backup status)_ ```js 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)_ ```js 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](#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)_ ```js server.getOutdatedClients().then((data) => console.log(data)); ``` **Example** _(Get outdated clients in a specific group)_ ```js server .getOutdatedClients({ groupName: 'exampleGroup' }) .then((data) => console.log(data)); ``` **Example** _(Get outdated clients, exclude clients marked for removal)_ ```js 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](#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)_ ```js server.getConflictingClients().then((data) => console.log(data)); ``` **Example** _(Get online clients with conflicting IP addresses, exclude clients marked for removal)_ ```js server .getConflictingClients({ includeRemoved: false }) .then((data) => console.log(data)); ``` ### urbackupServer.getUnseenClients([params]) ⇒ Promise.<Array.<object>> Retrieves a list of clients who have not been seen for a specified period of time. Defaults to 24 hours. **Kind**: instance method of [UrbackupServer](#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.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. Defaults to true. | | [params.timeThreshold] | number | 1440 | A time threshold, measured in minutes, after which a client is considered unseen. Defaults to 1440 minutes (24 hours). | **Example** _(Get clients not seen for more than 2 days)_ ```js server .getUnseenClients({ timeThreshold: 2880 }) .then((data) => console.log(data)); ``` ### urbackupServer.getStaleClients([params]) ⇒ Promise.<Array> Retrieves a list of clients that are considered "stale" (i.e., have backups older than the specified threshold). This method fetches all clients within a specified group and filters those that are stale based on their last backup times. Optionally, it can exclude blank clients (clients with no backups) from the results. **Kind**: instance method of [UrbackupServer](#UrbackupServer) **Returns**: Promise.<Array> - - A promise that resolves to an array of clients that are considered stale. **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.includeBlank] | boolean | true | Whether or not blank clients should be taken into account when matching clients. 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.timeThreshold] | number | 1440 | The time threshold (in minutes) for determining if a client is stale. Defaults to 1440 minutes (24 hours). | **Example** _(Get clients with file backup older than a day, skip blank clients)_ ```js server .getStaleClients({ includeBlank: false, includeImageBackups: false, timeThreshold: 1440, }) .then((data) => console.log(data)); ``` ### urbackupServer.addClient(params) ⇒ Promise.<boolean> Adds a new client. **Kind**: instance method of [UrbackupServer](#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)_ ```js 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](#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)_ ```js server.removeClient({ clientId: 1 }).then((data) => console.log(data)); ``` **Example** _(Remove client by name)_ ```js 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](#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)_ ```js server.cancelRemoveClient({ clientId: 1 }).then((data) => console.log(data)); ``` **Example** _(Stop the server from removing a client by name)_ ```js 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](#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)_ ```js 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](#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)_ ```js 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](#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)_ ```js 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](#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)_ ```js server.getClientSettings().then((data) => console.log(data)); ``` **Example** _(Get settings for a specific client only)_ ```js 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](#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)_ ```js 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.getClientGroup(params) ⇒ Promise.<(object\|null)> Retrieves the group information for a specific client. **Kind**: instance method of [UrbackupServer](#UrbackupServer) **Returns**: Promise.<(object\|null)> - A promise that resolves to an object containing the group ID and name, or null if the client or group is not found. **Throws**: - Error If parameters are missing or invalid, 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. | **Example** _(Get client group by client ID)_ ```js server.getClientGroup({ clientId: 1 }).then((data) => console.log(data)); ``` **Example** _(Get client group by client name)_ ```js server .getClientGroup({ clientName: 'laptop2' }) .then((data) => console.log(data)); ``` ### urbackupServer.setClientGroup(params) ⇒ Promise.<boolean> Sets the group for a specific client. **Kind**: instance method of [UrbackupServer](#UrbackupServer) **Returns**: Promise.<boolean> - A promise that resolves to true if the group was successfully set, or false otherwise. **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.groupId | number | Group ID. | **Example** _(Set client group by client ID)_ ```js server .setClientGroup({ clientId: 1, groupId: 123 }) .then((data) => console.log(data)); ``` **Example** _(Set client group by client name)_ ```js server .setClientGroup({ clientName: 'laptop2', groupId: 123 }) .then((data) => console.log(data)); ``` ### urbackupServer.getClientAuthkey(params) ⇒ Promise.<string> Retrieves the authentication key for a specified client. **Kind**: instance method of [UrbackupServer](#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)_ ```js 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](#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)_ ```js server.getStatus().then((data) => console.log(data)); ``` **Example** _(Get status for all clients, but skip clients marked for removal)_ ```js server.getStatus({ includeRemoved: false }).then((data) => console.log(data)); ``` **Example** _(Get status for a specific client only)_ ```js 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](#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)_ ```js server.getUsage().then((data) => console.log(data)); ``` **Example** _(Get usage for a specific client only)_ ```js 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](#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. | | [params.includePaused] | boolean | true | Whether or not paused activities should be included. Defaults to true. | **Example** _(Get current (in progress) activities for all clients)_ ```js server.getActivities({ includeLast: false }).then((data) => console.log(data)); ``` **Example** _(Get current (in progress, skip paused) activities for all clients)_ ```js server .getActivities({ includeLast: false, includePaused: false }) .then((data) => console.log(data)); ``` **Example** _(Get last activities for all clients)_ ```js server .getActivities({ includeCurrent: false }) .then((data) => console.log(data)); ``` **Example** _(Get current (in progress) activities for a specific client only)_ ```js 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)_ ```js 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](#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 | 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.includePaused] | boolean | true | Whether or not paused activities should be included. Defaults to true. | **Example** _(Get current activities for all clients)_ ```js server.getCurrentActivities().then((data) => console.log(data)); ``` **Example** _(Get current activities for all clients, skip paused activities)_ ```js server .getCurrentActivities({ includePaused: false }) .then((data) => console.log(data)); ``` **Example** _(Get current activities for a specific client only)_ ```js 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](#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)_ ```js server.getLastActivities().then((data) => console.log(data)); ``` **Example** _(Get last activities for a specific client only)_ ```js 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](#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)_ ```js server.getPausedActivities().then((data) => console.log(data)); ``` **Example** _(Get paused activities for a specific client only)_ ```js 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](#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)_ ```js 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](#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)_ ```js 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)_ ```js server .getBackups({ clientName: 'laptop1', includeFileBackups: false }) .then((data) => console.log(data)); ``` **Example** _(Get file backups for a specific client)_ ```js 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](#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)_ ```js server .startFullFileBackup({ clientName: 'laptop1' }) .then((data) => console.log(data)); ``` **Example** _(Start a full file backup by client ID)_ ```js server.startFullFileBackup({ clientId: 3 }).then((data) => console.log(data)); ``` ### urbackupServer.startIncrementalFileBackup(params) ⇒ Promise.<boolean> Starts an incremental file backup. **Kind**: instance method of [UrbackupServer](#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)_ ```js server .startIncrementalFileBackup({ clientName: 'laptop1' }) .then((data) => console.log(data)); ``` **Example** _(Start an incremental file backup by client ID)_ ```js server .startIncrementalFileBackup({ clientId: 3 }) .then((data) => console.log(data)); ``` ### urbackupServer.startFullImageBackup(params) ⇒ Promise.<boolean> Starts a full image backup. **Kind**: instance method of [UrbackupServer](#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)_ ```js server .startFullImageBackup({ clientName: 'laptop1' }) .then((data) => console.log(data)); ``` **Example** _(Start a full image backup by client ID)_ ```js server.startFullImageBackup({ clientId: 3 }).then((data) => console.log(data)); ``` ### urbackupServer.startIncrementalImageBackup(params) ⇒ Promise.<boolean> Starts an incremental image backup. **Kind**: instance method of [UrbackupServer](#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)_ ```js server .startIncrementalImageBackup({ clientName: 'laptop1' }) .then((data) => console.log(data)); ``` **Example** _(Start an incremental image backup by client ID)_ ```js 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](#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)_ ```js server.getLiveLog().then((data) => console.log(data)); ``` **Example** _(Get logs for a specific client only)_ ```js 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)_ ```js server .getLiveLog({ clientName: 'laptop1', recentOnly: true }) .then((data) => console.log(data)); ``` ### urbackupServer.getGeneralSettings() ⇒ Promise.<object> Retrieves general settings. **Kind**: instance method of [UrbackupServer](#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)_ ```js server.getGeneralSettings().then((data) => console.log(data)); ``` ### urbackupServer.getMailSettings() ⇒ Promise.<object> Retrieves mail settings. **Kind**: instance method of [UrbackupServer](#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)_ ```js server.getMailSettings().then((data) => console.log(data)); ``` ### urbackupServer.getLdapSettings() ⇒ Promise.<object> Retrieves LDAP settings. **Kind**: instance method of [UrbackupServer](#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)_ ```js 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](#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)_ ```js 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](#UrbackupServer) **Returns**: Promise.<object> - A promise that resolves to the raw status response object. **Throws**: - Error If the login fails. **Example** ```js 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](#UrbackupServer) **Returns**: Promise.<object> - A promise that resolves to the raw usage response object. **Throws**: - Error If the login fails. **Example** ```js 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](#UrbackupServer) **Returns**: Promise.<object> - A promise that resolves to the raw progress response object. **Throws**: - Error If the login fails. **Example** ```js const data = await urbackup.getRawProgress(); ```

c	File Name	Size	T	Date
-	LICENSE	1075	%	2026-10-07 19:30:57
-	README.md	99662	md	2026-10-07 19:30:57
-	index.js	119520	js	2026-10-07 19:30:57
-	package.json	848	json	2026-10-07 19:30:57

🌲 / homepage node_modules urbackup-server-api

control-panel