1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-SERVE" "1" "2025-12-01" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.SH SYNOPSIS
.sp
borg [common options] serve [options]
.SH DESCRIPTION
.sp
This command starts a repository server process. This command is usually not used manually.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS options
.INDENT 0.0
.TP
.BI \-\-restrict\-to\-path \ PATH
restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository.
.TP
.BI \-\-restrict\-to\-repository \ PATH
restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
.TP
.B \-\-append\-only
only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
.TP
.BI \-\-storage\-quota \ QUOTA
Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
.UNINDENT
.SH EXAMPLES
.sp
\fBborg serve\fP has special support for SSH forced commands (see \fBauthorized_keys\fP
example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will
ignore some options given on the command line and use the values from the
variable instead. This only applies to a carefully controlled allowlist of safe
options. This list currently contains:
.INDENT 0.0
.IP \(bu 2
Options that control the log level and debug topics printed
such as \fB\-\-verbose\fP, \fB\-\-info\fP, \fB\-\-debug\fP, \fB\-\-debug\-topic\fP, etc.
.IP \(bu 2
\fB\-\-lock\-wait\fP to allow the client to control how long to wait before
giving up and aborting the operation when another process is holding a lock.
.UNINDENT
.sp
Environment variables (such as BORG_XXX) contained in the original
command sent by the client are \fInot\fP interpreted; they are ignored. If BORG_XXX environment
variables need to be set on the \fBborg serve\fP side, then these must be set in system\-specific
locations like \fB/etc/environment\fP or in the forced command itself (example below).
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Allow an SSH key pair to only run borg, and only have access to /path/to/repo.
# Use key options to disable unneeded and potentially dangerous SSH functionality.
# This helps secure an automated remote backup system.
$ cat ~/.ssh/authorized_keys
command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rsa AAAAB3[...]
# Set a BORG_XXX environment variable on the \(ga\(gaborg serve\(ga\(ga side.
$ cat ~/.ssh/authorized_keys
command=\(dqBORG_XXX=value borg serve [...]\(dq,restrict ssh\-rsa [...]
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The examples above use the \fBrestrict\fP directive and assume a POSIX\-compliant
shell set as the user\(aqs login shell.
This automatically blocks potentially dangerous SSH features, even when
they are added in a future update. Thus, this option should be preferred.
.sp
If you\(aqre using OpenSSH server < 7.2, however, you have to explicitly specify
the SSH features to restrict and cannot simply use the \fBrestrict\fP option as it
was introduced in v7.2. We recommend using
\fBno\-port\-forwarding,no\-X11\-forwarding,no\-pty,no\-agent\-forwarding,no\-user\-rc\fP
in this case.
.UNINDENT
.UNINDENT
.sp
Details about sshd usage: sshd(8) <https://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8>
.SS SSH Configuration
.sp
\fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&.
.sp
In order to avoid this, it is recommended to perform the following additional SSH configuration:
.sp
Either in the client side\(aqs \fB~/.ssh/config\fP file, or in the client\(aqs \fB/etc/ssh/ssh_config\fP file:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Host backupserver
ServerAliveInterval 10
ServerAliveCountMax 30
.EE
.UNINDENT
.UNINDENT
.sp
Replace \fBbackupserver\fP with the hostname, FQDN, or IP address of the Borg server.
.sp
This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the SSH client process will be terminated, causing the Borg process to terminate gracefully.
.sp
On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/sshd_config\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
ClientAliveInterval 10
ClientAliveCountMax 30
.EE
.UNINDENT
.UNINDENT
.sp
This will cause the server to send a keepalive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
.sp
If you then run Borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the \fBborg serve\fP processes to terminate after the SSH connection is torn down following the 300\-second wait for the keepalives to fail.
.sp
You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case.
.sp
When the client is untrusted, it is a good idea to set the backup
user\(aqs shell to a simple implementation (\fB/bin/sh\fP is only an example and may or may
not be such a simple implementation):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
chsh \-s /bin/sh BORGUSER
.EE
.UNINDENT
.UNINDENT
.sp
Because the configured shell is used by openssh <https://www.openssh.com/>
to execute the command configured through the \fBauthorized_keys\fP file
using \fB\(dq$SHELL\(dq \-c \(dq$COMMAND\(dq\fP,
setting a minimal shell implementation reduces the attack surface
compared to when a feature\-rich and complex shell implementation is
used.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.
|
