python-urbackup 1.0.0

Python wrapper to access and control an UrBackup server

Python UrBackup

Python wrapper to interact with UrBackup servers. Manage backups, restore operations, and monitor server status programmatically.

Originally urbackup-server-web-api-wrapper

Installation

pip install python-urbackup

Quick Start

from urbackup import urbackup_server

server = urbackup_server("http://127.0.0.1:55414/x", "admin", "password")

if server.login():
    print("Connected!")

Legacy API (dict-based)

The legacy API returns raw dicts/lists, preserving backward compatibility.

from urbackup import urbackup_server

server = urbackup_server("http://127.0.0.1:55414/x", "admin", "password")

# Client status
clients = server.get_status()
for client in clients:
    print(f"{client['name']}: online={client['online']}")

# Start backups
server.start_incr_file_backup("my-client")
server.start_full_image_backup("my-client")

# Settings
settings = server.get_global_settings()
server.set_global_setting("backup_window", "1-5/8-17")

# Client settings
server.change_client_setting("my-client", "internet_speed", "50000")

# Extra clients
server.add_extra_client("10.0.0.5")
extras = server.get_extra_clients()

# Monitor actions
actions = server.get_actions()
for action in actions or []:
    server.stop_action(action)

# Live log
log = server.get_livelog()

Typed API (dataclass-based)

The typed API returns structured dataclass objects with full type hints.

from urbackup import urbackup_server, BackupType, ClientNotFoundError

server = urbackup_server("http://127.0.0.1:55414/x", "admin", "password")
server.login()

# Typed client statuses
clients = server.get_client_statuses()
for client in clients:
    print(f"{client.name}: id={client.id}, online={client.online}")

# Find specific client (raises ClientNotFoundError if missing)
try:
    client = server.get_client_status_by_name("my-client")
    print(f"Last backup: {client.lastbackup}")
except ClientNotFoundError:
    print("Client not found")

# Start backup with enum
server.start_backup_typed("my-client", BackupType.INCR_FILE)

# Typed usage stats
for entry in server.get_usage_typed():
    print(f"{entry.name}: {entry.used} bytes, {entry.files} files")

# Typed actions with progress
for action in server.get_actions_typed():
    print(f"Client {action.clientid}: {action.progress_percent}%")

# Typed settings (raises AccessDeniedError on failure)
settings = server.get_global_settings_typed()
server.set_global_setting_typed("backup_window", "1-7/0-24")

# Client settings (raises KeyError for invalid keys)
server.change_client_setting_typed("my-client", "internet_speed", "50000")

# Typed log entries
for entry in server.get_livelog_typed():
    print(f"[{entry.level}] {entry.message}")

# Backup history
backups = server.get_backups(clientid=1)
images = server.get_image_backups(clientid=1)

# Extra clients
for ec in server.get_extra_clients_typed():
    print(f"{ec.hostname} (id={ec.id})")

# Server identity
identity = server.get_server_identity_str()

Settings Example

Configure a client's backup folder path and incremental backup interval:

server.change_client_setting("my-client", "default_dirs", "/home;/etc")
server.change_client_setting("my-client", "update_freq_incr", "4")  # hours

Basic Auth (htpasswd)

If your server uses HTTP basic authentication:

server = urbackup_server(
    "http://127.0.0.1:55414/x", "admin", "password",
    basic_username="httpuser", basic_password="httppass",
)

Exception Hierarchy

UrbackupError
├── AuthenticationError    # login failed
├── ClientNotFoundError    # client name not found
├── AccessDeniedError      # insufficient permissions
└── UserAlreadyExistsError # duplicate user creation

Available Types

Type	Description
ClientStatus	Client info: id, name, online, lastbackup, ip, etc.
BackupEntry	Backup record: id, clientid, backuptime, size_bytes
UsageEntry	Storage usage: name, used, files, images
ActionProgress	Running action: clientid, id, action, progress_percent
LogEntry	Log record: id, message, level, time
ExtraClient	Extra client: id, hostname
User	User account: id, name, rights
Group	Client group: id, name
BackupType	Enum: INCR_FILE, FULL_FILE, INCR_IMAGE, FULL_IMAGE
ActionType	IntEnum: all server action type constants
InstallerOS	Enum: WINDOWS, LINUX
LogLevel	IntEnum: ERROR, WARNING, INFO, DEBUG

All dataclasses include a raw field with the original API dict.

UrBackup CLI

The UrBackup CLI is a command-line interface that allows you to interact with the UrBackup server from a client machine.

Important Note: For Windows the command-line tool is urbackupclient_cmd. Mac and Linux use urbackupclientctl.

CLI options for urbackupclientctl and urbackupclient_cmd are as follows:

USAGE:

        urbackupclientctl [--help] [--version] <command> [<args>]

Get specific command help with urbackupclientctl <command> --help

        urbackupclientctl start
                Start an incremental/full image/file backup

        urbackupclientctl status
                Get current backup status

        urbackupclientctl browse
                Browse backups and files/folders in backups

        urbackupclientctl restore-start
                Restore files/folders from backup

        urbackupclientctl set-settings
                Set backup settings

        urbackupclientctl reset-keep
                Reset keeping files during incremental backups

        urbackupclientctl add-backupdir
                Add new directory to backup set

        urbackupclientctl list-backupdirs
                List directories that are being backed up

        urbackupclientctl remove-backupdir
                Remove directory from backup set

For more information, please refer to the UrBackup Administration Documentation.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

License

This project is licensed under the Apache License - see the LICENSE file for details.