From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 29F741FF13C for ; Thu, 02 Apr 2026 00:53:31 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 1F7462C6D; Thu, 2 Apr 2026 00:54:00 +0200 (CEST) From: Thomas Lamprecht To: pbs-devel@lists.proxmox.com Subject: [PATCH v3 4/5] docs: document repository component options and env vars Date: Thu, 2 Apr 2026 00:49:00 +0200 Message-ID: <20260401225305.4069441-5-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260401225305.4069441-1-t.lamprecht@proxmox.com> References: <20260401225305.4069441-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1775083948048 X-SPAM-LEVEL: Spam detection results: 0 AWL -1.499 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 1 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 1 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 1 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: EUHI22SW4KLLTKG23KTA45ZETNVRWEN4 X-Message-ID-Hash: EUHI22SW4KLLTKG23KTA45ZETNVRWEN4 X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox Backup Server development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Document the new --server, --port, --datastore, and --auth-id CLI options, their mutual exclusion with --repository, per-field merge behavior with PBS_* environment variables, and the corresponding PBS_SERVER, PBS_PORT, PBS_DATASTORE, PBS_AUTH_ID variables. Signed-off-by: Thomas Lamprecht --- no changes since v2. docs/backup-client.rst | 61 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/backup-client.rst b/docs/backup-client.rst index cc45a35ba..1d464a007 100644 --- a/docs/backup-client.rst +++ b/docs/backup-client.rst @@ -28,6 +28,50 @@ brackets (for example, `[fe80::01]`). You can pass the repository with the ``--repository`` command-line option, or by setting the ``PBS_REPOSITORY`` environment variable. +Alternatively, you can specify the repository components as separate +command-line options: + +``--server `` + Backup server address (hostname or IP address). Defaults to ``localhost``. + Requires ``--datastore`` to be set as well. + +``--port `` + Backup server port. Defaults to ``8007``. + +``--datastore `` + Name of the target datastore. Required when using component options instead + of ``--repository``. + +``--auth-id `` + Authentication identity, either a user (``user@realm``) or an API token + (``user@realm!tokenname``). Defaults to ``root@pam``. + +These options are mutually exclusive with ``--repository``. Both forms resolve +to the same internal representation, so cached login tickets and other session +state are shared between them. For example, logging in with ``--repository`` +and then running a backup with ``--server``/``--datastore`` (or vice versa) +reuses the same ticket, as long as the server address and user match. + +When component options are used on the command line, they are merged with the +corresponding ``PBS_*`` environment variables on a per-field basis: CLI options +take precedence, while unspecified fields fall back to their environment +variable. For example, with ``PBS_SERVER`` and ``PBS_DATASTORE`` set in the +environment, passing ``--auth-id 'other@pam'`` on the command line overrides +just the identity while inheriting the server and datastore from the +environment. + +The component options make it easy to change individual parts of the +connection, for example switching to a different datastore or server without +having to rewrite the entire repository string: + +.. code-block:: console + + # proxmox-backup-client backup root.pxar:/ \ + --auth-id 'user@pbs!backup' --server pbs.example.com --datastore store1 + +.. Note:: Remember to quote API token identifiers on the shell, since the + exclamation mark (``!``) is a special character in most shells. + The web interface provides copyable repository text in the datastore summary with the `Show Connection Information` button. @@ -70,6 +114,23 @@ Environment Variables ``PBS_REPOSITORY`` The default backup repository. +``PBS_SERVER`` + Backup server address. Provides a default that can be overridden by + ``--server``. Requires ``PBS_DATASTORE`` to be set as well (unless + ``--datastore`` is given on the command line). Not used when ``--repository`` + or ``PBS_REPOSITORY`` is set. + +``PBS_PORT`` + Backup server port. Defaults to ``8007`` if unset. + +``PBS_DATASTORE`` + Datastore name. Provides a default that can be overridden by ``--datastore``. + Not used when ``--repository`` or ``PBS_REPOSITORY`` is set. + +``PBS_AUTH_ID`` + Authentication identity (``user@realm`` or ``user@realm!tokenname``). + Defaults to ``root@pam`` if unset. + ``PBS_PASSWORD`` When set, this value is used as the password for the backup server. You can also set this to an API token secret. -- 2.47.3