{"id":12323,"library":"urbackup-server-api","title":"UrBackup Server API Client for Node.js","description":"The `urbackup-server-api` module provides a Node.js interface for programmatic interaction with the UrBackup server's web API. It enables comprehensive management and monitoring of backup operations, including manipulating server and client settings, group management, task monitoring, initiating/stopping backups, accessing live logs, and fetching backup history. The current stable version is 0.92.2, indicating it is under active development and has not yet reached a 1.0.0 release. The project exhibits an iterative release cadence, with minor versions introducing new features and occasional method signature adjustments. Its primary differentiation lies in simplifying the automation and integration of UrBackup server administration directly within Node.js applications, making it valuable for server administrators and developers. Due to its pre-1.0 status, users should be aware that method signatures and functionality may change without major version bumps, necessitating a review of the CHANGELOG before updates.","status":"active","version":"0.92.2","language":"javascript","source_language":"en","source_url":"https://github.com/bartmichu/node-urbackup-server-api","tags":["javascript","urbackup"],"install":[{"cmd":"npm install urbackup-server-api","lang":"bash","label":"npm"},{"cmd":"yarn add urbackup-server-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add urbackup-server-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { UrbackupServer } = require('urbackup-server-api');","symbol":"UrbackupServer","correct":"import { UrbackupServer } from 'urbackup-server-api';"},{"note":"UrbackupServer is a named export, not a default export. Attempting to import it as a default will result in an undefined value.","wrong":"import UrbackupServer from 'urbackup-server-api';","symbol":"UrbackupServer","correct":"import { UrbackupServer } from 'urbackup-server-api';"},{"note":"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.","wrong":"import * as UrbackupAPI from 'urbackup-server-api';","symbol":"UrbackupServer","correct":"import { UrbackupServer } from 'urbackup-server-api';"}],"quickstart":{"code":"import { UrbackupServer } from 'urbackup-server-api';\n\n// When troubleshooting TSL connections with self-signed certificates, you may try to disable certificate validation.\n// Keep in mind that it's strongly discouraged for production use.\n// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';\n\nconst server = new UrbackupServer({\n  url: process.env.URBACKUP_URL ?? 'http://127.0.0.1:55414',\n  username: process.env.URBACKUP_USERNAME ?? 'admin',\n  password: process.env.URBACKUP_PASSWORD ?? 'secretpassword',\n});\n\n(async () => {\n  try {\n    // Check if server is currently busy\n    const activities = await server.getCurrentActivities();\n    console.log(`Server Busy: ${activities.length > 0}`);\n\n    // Get a list of clients in the 'prod' group\n    const prodClients = await server.getGroupMembers({ groupName: 'prod' });\n    console.log('Production Clients:', prodClients.map(c => c.name));\n\n    // Get production clients with failed image backup\n    const failedClients = await server.getFailedClients({ groupName: 'prod', includeFileBackups: false });\n    console.log('Failed Image Backups in Prod:', failedClients.map(c => c.name));\n\n    // Get all clients without both file and image backups\n    const blankClients = await server.getBlankClients();\n    console.log('Clients without any backups:', blankClients.map(c => c.name));\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n  }\n})();","lang":"javascript","description":"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."},"warnings":[{"fix":"Consult the package's `CHANGELOG.md` for specific breaking changes and adjust your code accordingly after each minor version update.","message":"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.","severity":"breaking","affected_versions":">=0.91.0"},{"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.","message":"In version 0.92.0, the `getGroupMembers()` method changed its precedence. If both `groupId` and `groupName` are provided, `groupId` will now take precedence.","severity":"breaking","affected_versions":">=0.92.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.91.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The UrBackup server is either not running, not accessible at the specified URL and port, or a firewall is blocking the connection.","error":"connect ECONNREFUSED <ip-address>:<port>"},{"fix":"Double-check the `username` and `password` parameters against your UrBackup server's user credentials. Ensure the user has the necessary API access rights.","cause":"The credentials provided to the `UrbackupServer` constructor (username and password) are incorrect for accessing the UrBackup API.","error":"Error: Invalid username or password"},{"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.","cause":"The UrBackup server is using a self-signed SSL/TLS certificate, which Node.js does not trust by default.","error":"Error: self-signed certificate in certificate chain (CODE: DEPTH_ZERO_SELF_SIGNED_CERT)"}],"ecosystem":"npm"}