UrBackup Server API Client for Node.js

Common errors

• connect ECONNREFUSED <ip-address>:<port>

  cause The UrBackup server is either not running, not accessible at the specified URL and port, or a firewall is blocking the connection.
  fix Verify that the UrBackup server is online and reachable from your Node.js application. Check the `url` parameter in your `UrbackupServer` constructor and ensure no firewall rules are preventing access.

• Error: Invalid username or password

  cause The credentials provided to the `UrbackupServer` constructor (username and password) are incorrect for accessing the UrBackup API.
  fix Double-check the `username` and `password` parameters against your UrBackup server's user credentials. Ensure the user has the necessary API access rights.

• Error: self-signed certificate in certificate chain (CODE: DEPTH_ZERO_SELF_SIGNED_CERT)

  cause The UrBackup server is using a self-signed SSL/TLS certificate, which Node.js does not trust by default.
  fix For development, you can temporarily set `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'` (highly discouraged for production). The correct fix is to configure a trusted SSL certificate on your UrBackup server or provide Node.js with the necessary CA certificate to trust the self-signed certificate.

Warnings

• breaking The module is currently in pre-1.0.0 release. Method signatures and functionality may change without notice between minor versions. Always review the `CHANGELOG.md` before updating.
  Fix: Consult the package's `CHANGELOG.md` for specific breaking changes and adjust your code accordingly after each minor version update.
• breaking In version 0.92.0, the `getGroupMembers()` method changed its precedence. If both `groupId` and `groupName` are provided, `groupId` will now take precedence.
  Fix: If your application relies on `groupName` when both parameters are present for `getGroupMembers()`, explicitly remove the `groupId` parameter or ensure `groupId` is the intended filter.
• gotcha Disabling TLS certificate validation via `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'` is strongly discouraged for production use as it bypasses critical security checks, making your application vulnerable to man-in-the-middle attacks.
  Fix: Ensure your UrBackup server uses valid, trusted TLS certificates. For self-signed certificates in non-production environments, consider adding the certificate to your system's trust store or configuring Node.js to trust it without broadly disabling rejection.

Install

• npm install urbackup-server-api npm
• yarn add urbackup-server-api yarn
• pnpm add urbackup-server-api pnpm

Imports

• UrbackupServer
  wrong:

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

  correct:

  import { UrbackupServer } from 'urbackup-server-api';

  The library primarily uses ESM `import` syntax as shown in the examples. While CommonJS `require` might technically work in some environments, ESM is the recommended and documented approach.
• UrbackupServer
  wrong:

  import UrbackupServer from 'urbackup-server-api';

  correct:

  import { UrbackupServer } from 'urbackup-server-api';

  UrbackupServer is a named export, not a default export. Attempting to import it as a default will result in an undefined value.
• UrbackupServer
  wrong:

  import * as UrbackupAPI from 'urbackup-server-api';

  correct:

  import { UrbackupServer } from 'urbackup-server-api';

  While `import * as` might technically allow access to `UrbackupAPI.UrbackupServer`, the recommended way to import the main class is via named import for clarity and tree-shaking benefits.

Quickstart

This example initializes the UrbackupServer client and demonstrates how to retrieve server activity, list clients by group, and identify clients with failed or missing backups.

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: process.env.URBACKUP_URL ?? 'http://127.0.0.1:55414',
  username: process.env.URBACKUP_USERNAME ?? 'admin',
  password: process.env.URBACKUP_PASSWORD ?? 'secretpassword',
});

(async () => {
  try {
    // Check if server is currently busy
    const activities = await server.getCurrentActivities();
    console.log(`Server Busy: ${activities.length > 0}`);

    // Get a list of clients in the 'prod' group
    const prodClients = await server.getGroupMembers({ groupName: 'prod' });
    console.log('Production Clients:', prodClients.map(c => c.name));

    // Get production clients with failed image backup
    const failedClients = await server.getFailedClients({ groupName: 'prod', includeFileBackups: false });
    console.log('Failed Image Backups in Prod:', failedClients.map(c => c.name));

    // Get all clients without both file and image backups
    const blankClients = await server.getBlankClients();
    console.log('Clients without any backups:', blankClients.map(c => c.name));
  } catch (error) {
    console.error('An error occurred:', error.message);
  }
})();