| Name | smb-zfs JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | None |
| Summary | A tool to manage Samba on a ZFS-backed system. |
| upload_time | 2025-08-04 10:43:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
zfs
samba
debian
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Samba & ZFS Management Tool
A command-line tool for simplifying Samba share management on ZFS-backed systems.
`smb-zfs` automates the setup and administration of users, groups, and shares, ensuring Samba and ZFS configurations remain synchronized.
It provides a reliable interface for common administrative tasks through two modes: a standard CLI `smb-zfs` for scripting and an interactive wizard `smb-zfs wizard` for guided setup.
```text
$ smb-zfs -h
usage: smb-zfs [-h] [--version] [-v] {wizard,setup,create,modify,delete,list,passwd,remove,get-state} ...
A tool to manage Samba on a ZFS-backed system.
positional arguments:
{wizard,setup,create,modify,delete,list,passwd,remove,get-state}
Available commands
wizard Start an interactive wizard for common tasks.
setup Set up and configure Samba, ZFS, and Avahi.
create Create a new user, share, or group.
modify Modify an existing user, share, or group.
delete Delete a user, share, or group.
list List all managed users, shares, groups or pools.
passwd Change a user's Samba password.
remove Uninstall smb-zfs and remove all related configurations and data.
get-state Print the current state as JSON.
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose Increase verbosity level (-v for warning, -vv for info, -vvv for debug).
```
## Prerequisites
- Debian 12 - Bookworm
- ZFS installed with a pre-existing pool
- Python 3.11
- `sudo` privileges
## Installation
Install package:
```shell
sudo apt update
sudo apt install -y pipx samba avahi-daemon
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install smb-zfs
echo PIPX_HOME=/opt/pipx >> ~/.bashrc
echo PIPX_BIN_DIR=/usr/local/bin >> ~/.bashrc
```
Install `bash` completion:
```Shell
wget "https://raw.githubusercontent.com/mietzen/smb-zfs/refs/tags/$(smb-zfs -v)/completion/smb-zfs-completion.sh" -O /etc/bash_completion.d/smb-zfs-completion.sh
```
This makes the `smb-zfs` command available system-wide.
## Quick Start: Use the Wizard for Guided Setup
```shell
$ smb-zfs --help
usage: smb-zfs [-h] [--version] [-v] {wizard,setup,create,modify,delete,list,passwd,remove,get-state} ...
A tool to manage Samba on a ZFS-backed system.
positional arguments:
{wizard,setup,create,modify,delete,list,passwd,remove,get-state}
Available commands
wizard Start an interactive wizard for common tasks.
setup Set up and configure Samba, ZFS, and Avahi.
create Create a new user, share, or group.
modify Modify an existing user, share, or group.
delete Delete a user, share, or group.
list List all managed users, shares, groups or pools.
passwd Change a user's Samba password.
remove Uninstall smb-zfs and remove all related configurations and data.
get-state Print the current state as JSON.
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose Increase verbosity level (-v for warning, -vv for info, -vvv for debug).
```
Example setup:
```shell
$ smb-zfs wizard setup
--- Initial System Setup Wizard ---
Available ZFS pools: data, rpool, tank
Enter the name of the ZFS pool to use: tank
Enter the server's NetBIOS name [nas]:
Enter the workgroup name [WORKGROUP]:
Enable macOS compatibility optimizations? [y/N] [n]: y
Enter a default quota for user homes (e.g., 10G, optional): 20G
Summary of actions:
- ZFS Pool: tank
- Server Name: nas
- Workgroup: WORKGROUP
- macOS Optimized: True
- Default Home Quota: 20G
Proceed with setup? [Y/n] [y]:
Success: Setup completed successfully.
```
```shell
$ smb-zfs wizard create user
--- Create New User Wizard ---
Enter the new username: nils
Enter password for user 'nils':
Confirm password:
Allow shell access (/bin/bash)? [y/N] [n]: y
Available groups: smb_users
Enter comma-separated groups to add user to (optional): smb_users
Success: User 'nils' created successfully.
```
```shell
$ smb-zfs wizard create share
--- Create New Share Wizard ---
Enter the name for the new share: media
Enter the ZFS dataset path within the pool (e.g., data/media): media
Enter a comment for the share (optional): Movies, Series, Music, etc.
Available users: nils
Enter the owner for the share's files (default: root):
Available groups: smb_users
Enter the group for the share's files (default: smb_users):
Enter file system permissions for the share root [0775]:
Enter valid users/groups (e.g., @smb_users) [@smb_users]:
Make the share read-only? [y/N] [n]:
Make the share browseable? [Y/n] [y]:
Enter a ZFS quota for this share (e.g., 100G, optional): 500G
Success: Share 'media' created successfully.
```
## Advanced CLI usage
All commands must be run with root privileges.
Initial Setup:
```shell
sudo smb-zfs install --pool <your-zfs-pool> --default-home-quota 20G
```
Create a User:
```shell
sudo smb-zfs create user john --shell
```
Create a Share:
```shell
# Creates the dataset 'your-zfs-pool/data/media' with a 500G quota
sudo smb-zfs create share media --dataset data/media --quota 500G
```
Modify a Share's Quota:
```shell
sudo smb-zfs modify share media --quota 600G
```
## Update `smb-zfs`
```shell
pipx upgrade smb-zfs
```
## Uninstallation
```shell
sudo smb-zfs wizard remove
sudo pipx remove smb-zfs
# Remove apt pkgs
sudo apt remove pipx samba samba-common-bin avahi-daemon
```
Raw data
{
"_id": null,
"home_page": null,
"name": "smb-zfs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "zfs, samba, debian",
"author": null,
"author_email": "Nils Stein <github.nstein@mailbox.org>",
"download_url": null,
"platform": null,
"description": "# Samba & ZFS Management Tool\n\nA command-line tool for simplifying Samba share management on ZFS-backed systems.\n\n`smb-zfs` automates the setup and administration of users, groups, and shares, ensuring Samba and ZFS configurations remain synchronized.\n\nIt provides a reliable interface for common administrative tasks through two modes: a standard CLI `smb-zfs` for scripting and an interactive wizard `smb-zfs wizard` for guided setup.\n\n```text\n$ smb-zfs -h\nusage: smb-zfs [-h] [--version] [-v] {wizard,setup,create,modify,delete,list,passwd,remove,get-state} ...\n\nA tool to manage Samba on a ZFS-backed system.\n\npositional arguments:\n {wizard,setup,create,modify,delete,list,passwd,remove,get-state}\n Available commands\n wizard Start an interactive wizard for common tasks.\n setup Set up and configure Samba, ZFS, and Avahi.\n create Create a new user, share, or group.\n modify Modify an existing user, share, or group.\n delete Delete a user, share, or group.\n list List all managed users, shares, groups or pools.\n passwd Change a user's Samba password.\n remove Uninstall smb-zfs and remove all related configurations and data.\n get-state Print the current state as JSON.\n\noptions:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -v, --verbose Increase verbosity level (-v for warning, -vv for info, -vvv for debug).\n```\n\n## Prerequisites\n\n - Debian 12 - Bookworm\n - ZFS installed with a pre-existing pool\n - Python 3.11\n - `sudo` privileges\n\n## Installation\n\nInstall package:\n\n```shell\nsudo apt update\nsudo apt install -y pipx samba avahi-daemon\nsudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install smb-zfs\necho PIPX_HOME=/opt/pipx >> ~/.bashrc\necho PIPX_BIN_DIR=/usr/local/bin >> ~/.bashrc\n```\n\nInstall `bash` completion:\n\n```Shell\nwget \"https://raw.githubusercontent.com/mietzen/smb-zfs/refs/tags/$(smb-zfs -v)/completion/smb-zfs-completion.sh\" -O /etc/bash_completion.d/smb-zfs-completion.sh\n```\n\nThis makes the `smb-zfs` command available system-wide.\n\n## Quick Start: Use the Wizard for Guided Setup\n\n```shell\n$ smb-zfs --help\nusage: smb-zfs [-h] [--version] [-v] {wizard,setup,create,modify,delete,list,passwd,remove,get-state} ...\n\nA tool to manage Samba on a ZFS-backed system.\n\npositional arguments:\n {wizard,setup,create,modify,delete,list,passwd,remove,get-state}\n Available commands\n wizard Start an interactive wizard for common tasks.\n setup Set up and configure Samba, ZFS, and Avahi.\n create Create a new user, share, or group.\n modify Modify an existing user, share, or group.\n delete Delete a user, share, or group.\n list List all managed users, shares, groups or pools.\n passwd Change a user's Samba password.\n remove Uninstall smb-zfs and remove all related configurations and data.\n get-state Print the current state as JSON.\n\noptions:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -v, --verbose Increase verbosity level (-v for warning, -vv for info, -vvv for debug).\n```\n\nExample setup:\n\n```shell\n$ smb-zfs wizard setup\n\n--- Initial System Setup Wizard ---\nAvailable ZFS pools: data, rpool, tank\nEnter the name of the ZFS pool to use: tank\nEnter the server's NetBIOS name [nas]:\nEnter the workgroup name [WORKGROUP]:\nEnable macOS compatibility optimizations? [y/N] [n]: y\nEnter a default quota for user homes (e.g., 10G, optional): 20G\n\nSummary of actions:\n - ZFS Pool: tank\n - Server Name: nas\n - Workgroup: WORKGROUP\n - macOS Optimized: True\n - Default Home Quota: 20G\nProceed with setup? [Y/n] [y]:\n\nSuccess: Setup completed successfully.\n```\n\n```shell\n$ smb-zfs wizard create user\n\n--- Create New User Wizard ---\nEnter the new username: nils\nEnter password for user 'nils':\nConfirm password:\nAllow shell access (/bin/bash)? [y/N] [n]: y\nAvailable groups: smb_users\nEnter comma-separated groups to add user to (optional): smb_users\n\nSuccess: User 'nils' created successfully.\n```\n\n```shell\n$ smb-zfs wizard create share\n\n--- Create New Share Wizard ---\nEnter the name for the new share: media\nEnter the ZFS dataset path within the pool (e.g., data/media): media\nEnter a comment for the share (optional): Movies, Series, Music, etc.\nAvailable users: nils\nEnter the owner for the share's files (default: root):\nAvailable groups: smb_users\nEnter the group for the share's files (default: smb_users):\nEnter file system permissions for the share root [0775]:\nEnter valid users/groups (e.g., @smb_users) [@smb_users]:\nMake the share read-only? [y/N] [n]:\nMake the share browseable? [Y/n] [y]:\nEnter a ZFS quota for this share (e.g., 100G, optional): 500G\n\nSuccess: Share 'media' created successfully.\n```\n\n## Advanced CLI usage\n\nAll commands must be run with root privileges.\n\nInitial Setup:\n\n```shell\nsudo smb-zfs install --pool <your-zfs-pool> --default-home-quota 20G\n```\n\nCreate a User:\n\n```shell\nsudo smb-zfs create user john --shell\n```\n\nCreate a Share:\n\n```shell\n# Creates the dataset 'your-zfs-pool/data/media' with a 500G quota\nsudo smb-zfs create share media --dataset data/media --quota 500G\n```\n\nModify a Share's Quota:\n\n```shell\nsudo smb-zfs modify share media --quota 600G\n```\n\n## Update `smb-zfs`\n\n```shell\npipx upgrade smb-zfs\n```\n\n## Uninstallation\n\n```shell\nsudo smb-zfs wizard remove\nsudo pipx remove smb-zfs\n\n# Remove apt pkgs\nsudo apt remove pipx samba samba-common-bin avahi-daemon\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool to manage Samba on a ZFS-backed system.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/mietzen/smb-zfs",
"Issues": "https://github.com/mietzen/smb-zfs/issues"
},
"split_keywords": [
"zfs",
" samba",
" debian"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8604d1f9c16b9444503abcdf39acf0f796908586e75cd9b5c7b752e03150feea",
"md5": "e8eef9f0655c5ec7f43d0c39ed674692",
"sha256": "3dc86a34dee4b9a678de37e0c0865a2007f34c0068a8b33ca0075ccc6aa9fc12"
},
"downloads": -1,
"filename": "smb_zfs-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8eef9f0655c5ec7f43d0c39ed674692",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 33181,
"upload_time": "2025-08-04T10:43:02",
"upload_time_iso_8601": "2025-08-04T10:43:02.821718Z",
"url": "https://files.pythonhosted.org/packages/86/04/d1f9c16b9444503abcdf39acf0f796908586e75cd9b5c7b752e03150feea/smb_zfs-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 10:43:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mietzen",
"github_project": "smb-zfs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smb-zfs"
}
