SMB / CIFS

SMB (Server Message Block), also known as CIFS, is the file-sharing protocol used by Windows networks and by NAS appliances and Samba servers on Unix. It is the standard way to share folders, called shares, across a LAN.

The SMB integration walks a share over SMB2/3 and captures its files, directories, and symlinks into a Kloset store with encryption and deduplication. Plakar speaks the protocol directly over TCP, so no kernel mount, no system smbclient, and no root privileges are required. Authentication uses NTLMv2.

The SMB integration provides two connectors:

Installation

The SMB package can be installed using pre-built binaries or compiled from source.

$ plakar pkg add smb

$ plakar pkg show

$ plakar pkg build smb

$ plakar pkg add ./smb_v1.0.0_darwin_arm64.ptar

$ plakar pkg show

To list, upgrade, or remove the package, see managing packages guide.

Configuration

Addressing a share

An SMB location identifies the server and the share to mount:

smb://[<user>[:<password>]@]<host>[:<port>]/<share>[/<subpath>]

The first path segment is the share to mount. Anything deeper narrows the walk to a subtree of that share, which the root option also does. Credentials can be supplied in the URL userinfo or as separate options.

Configuration options

These options apply to both connectors.

Source connector

The source connector walks the share, or a subtree of it, and stores the files, directories, and symlinks it finds in a Kloset store with encryption and deduplication. Each entry is captured with its size and modification time.

flowchart LR

subgraph Source["SMB Share"]
  FS["Files"]
end

subgraph Plakar["Plakar"]
  Connector["Walk share via
SMB2/3"]
  Transform["Encrypt & deduplicate"]
  Connector --> Transform
end

Source --> Connector

Store["Kloset Store"]
Transform --> Store

Register the source and run a backup:

$ plakar source add my-smb-share \
  location=smb://nas.example.com/documents \
  username=<YOUR_USERNAME> \
  password=<YOUR_PASSWORD>

$ plakar at /var/backups backup "@my-smb-share"

To back up a subtree rather than the whole share, extend the location with the path inside the share:

$ plakar source add my-smb-projects \
  location=smb://nas.example.com/documents/projects \
  username=<YOUR_USERNAME> \
  password=<YOUR_PASSWORD>

A location can also be passed directly to backup, with credentials in the URL or as options:

$ plakar at /var/backups backup smb://alice:secret@nas.example.com/documents

$ plakar at /var/backups backup \
  -o username=alice -o password=secret \
  smb://nas.example.com/documents/projects

Destination connector

Restores a snapshot from a Kloset store back to an SMB share, recreating the directory hierarchy, file contents, and symlinks.

flowchart LR

Store["Kloset Store"]

subgraph Plakar["Plakar"]
  Transform["Decrypt & reconstruct"]
  Connector["Write files via
SMB2/3"]
  Transform --> Connector
end

Store --> Transform

subgraph Destination["SMB Share"]
  FS["Files"]
end

Connector --> Destination

Register the destination and restore a snapshot:

$ plakar destination add my-smb-restore \
  location=smb://nas.example.com/restore \
  username=<YOUR_USERNAME> \
  password=<YOUR_PASSWORD>

$ plakar at /var/backups restore -to "@my-smb-restore" <snapshot_id>

Limitations

Authentication

Authentication is NTLMv2. Kerberos is not supported.

File metadata

SMB has no native Unix ownership or permission model. Backed-up files carry a mode synthesized from their DOS attributes, meaning the directory and read-only flags. User and group IDs, inode numbers, and link counts are not available.

On restore, file contents, directories, and symlinks are recreated, and modification times are preserved on a best-effort basis. Unix permission bits and ownership are not restored.

Unsupported file types

Device nodes, sockets, and FIFOs have no SMB representation. Restoring a snapshot that contains them reports an error for each such entry.