0
# Utility Operations
1

2
Utility commands for version information, help, benchmarking, and advanced repository operations.
3

4
```python
5
import subprocess
6
import json
7
```
8

9
## Capabilities
10

11
### Version Information
12

13
Get version information for both client and server components.
14

15
```python { .api }
16
def get_version_info(server_repo: str = None) -> str:
17
    """
18
    Get BorgBackup version information.
19
    
20
    Args:
21
        server_repo: Repository path to get server version (optional)
22
        
23
    Returns:
24
        Version information string
25
    """
26
    cmd = ['borg', 'version']
27
    if server_repo:
28
        cmd.append(server_repo)
29
    
30
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
31
    return result.stdout.strip()
32
```
33

34
Usage example:
35
```python
36
import subprocess
37

38
# Get client version
39
result = subprocess.run(['borg', 'version'], capture_output=True, text=True, check=True)
40
client_version = result.stdout.strip()
41
print(f"Borg client version: {client_version}")
42

43
# Get server version (if using remote repository)
44
result = subprocess.run(['borg', 'version', 'user@server:/backup/repo'], 
45
                       capture_output=True, text=True, check=True)
46
server_version = result.stdout.strip()
47
```
48

49
### Help System
50

51
Access detailed help information for commands and topics.
52

53
```python { .api }
54
def get_help(topic: str = None) -> str:
55
    """
56
    Get help information.
57
    
58
    Args:
59
        topic: Specific topic or command to get help for (optional)
60
        
61
    Returns:
62
        Help text
63
    """
64
    cmd = ['borg', 'help']
65
    if topic:
66
        cmd.append(topic)
67
    
68
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
69
    return result.stdout
70
```
71

72
Usage example:
73
```python
74
import subprocess
75

76
# Get general help
77
result = subprocess.run(['borg', 'help'], capture_output=True, text=True, check=True)
78
general_help = result.stdout
79

80
# Get help for specific command
81
result = subprocess.run(['borg', 'help', 'create'], 
82
                       capture_output=True, text=True, check=True)
83
create_help = result.stdout
84

85
# Get help for specific topics
86
available_topics = ['patterns', 'placeholders', 'compression']
87
for topic in available_topics:
88
    result = subprocess.run(['borg', 'help', topic], 
89
                           capture_output=True, text=True, check=True)
90
    topic_help = result.stdout
91
```
92

93
### Benchmark Operations
94

95
Perform benchmark tests to measure BorgBackup performance on your system.
96

97
```python { .api }
98
def benchmark_crud(repo_path: str, path: str, file_size: int = 10485760,
99
                  file_count: int = 40, data_seed: int = None) -> None:
100
    """
101
    Benchmark CRUD (Create, Read, Update, Delete) operations.
102
    
103
    Args:
104
        repo_path: Path to repository for benchmarking
105
        path: Path to directory for benchmark files
106
        file_size: Size of each test file in bytes (default: 10MB)
107
        file_count: Number of files to create (default: 40)
108
        data_seed: Seed for random data generation
109
    """
110
    cmd = ['borg', 'benchmark', 'crud', repo_path, path]
111
    if file_size != 10485760:
112
        cmd.extend(['--file-size', str(file_size)])
113
    if file_count != 40:
114
        cmd.extend(['--file-count', str(file_count)])
115
    if data_seed:
116
        cmd.extend(['--data-seed', str(data_seed)])
117
    
118
    subprocess.run(cmd, check=True)
119
```
120

121
Usage example:
122
```python
123
import subprocess
124

125
# Run standard benchmark
126
subprocess.run([
127
    'borg', 'benchmark', 'crud', '/benchmark/repo', '/tmp/benchmark'
128
], check=True)
129

130
# Run benchmark with custom parameters
131
subprocess.run([
132
    'borg', 'benchmark', 'crud', 
133
    '--file-size=1048576',  # 1MB files
134
    '--file-count=100',     # 100 files
135
    '/benchmark/repo', '/tmp/benchmark'
136
], check=True)
137
```
138

139
### Lock Management
140

141
Advanced lock management for running commands with repository locks held.
142

143
```python { .api }
144
def with_lock(repo_path: str, command: list, wait: int = None) -> None:
145
    """
146
    Run command with repository lock held.
147
    
148
    Args:
149
        repo_path: Path to repository
150
        command: Command to run while holding lock
151
        wait: Maximum time to wait for lock in seconds
152
    """
153
    cmd = ['borg', 'with-lock']
154
    if wait:
155
        cmd.extend(['--lock-wait', str(wait)])
156
    cmd.append(repo_path)
157
    cmd.extend(command)
158
    
159
    subprocess.run(cmd, check=True)
160
```
161

162
Usage example:
163
```python
164
import subprocess
165

166
# Run custom script with repository lock
167
subprocess.run([
168
    'borg', 'with-lock', '/backup/repo',
169
    'python', '/scripts/backup-maintenance.py'
170
], check=True)
171

172
# Run command with lock timeout
173
subprocess.run([
174
    'borg', 'with-lock', '--lock-wait=300',  # Wait up to 5 minutes
175
    '/backup/repo', 'rsync', '-av', '/data/', '/backup/staging/'
176
], check=True)
177
```
178

179
### Repository Serving
180

181
Serve repository for remote access with security restrictions and performance options.
182

183
```python { .api }
184
def serve_repository_advanced(restrict_paths: list = None, 
185
                            restrict_repos: list = None,
186
                            append_only: bool = False,
187
                            storage_quota: str = None,
188
                            umask: str = None) -> None:
189
    """
190
    Serve repository with advanced options (typically called via SSH).
191
    
192
    Args:
193
        restrict_paths: List of allowed path prefixes
194
        restrict_repos: List of allowed repository paths  
195
        append_only: Allow only append operations
196
        storage_quota: Set storage quota limit (e.g., '5G', '100M')
197
        umask: Set umask for created files (octal, e.g., '0077')
198
    """
199
    cmd = ['borg', 'serve']
200
    if restrict_paths:
201
        for path in restrict_paths:
202
            cmd.extend(['--restrict-to-path', path])
203
    if restrict_repos:
204
        for repo in restrict_repos:
205
            cmd.extend(['--restrict-to-repository', repo])
206
    if append_only:
207
        cmd.append('--append-only')
208
    if storage_quota:
209
        cmd.extend(['--storage-quota', storage_quota])
210
    if umask:
211
        cmd.extend(['--umask', umask])
212
    
213
    subprocess.run(cmd, check=True)
214
```
215

216
Usage example:
217
```python
218
import subprocess
219

220
# Typical SSH authorized_keys entry for restricted serve
221
# command="borg serve --restrict-to-path /backup/repos --append-only" ssh-rsa AAAA...
222

223
# Serve with multiple restrictions
224
# command="borg serve --restrict-to-repository /backup/user1 --restrict-to-repository /backup/user2 --storage-quota 10G" ssh-rsa AAAA...
225
```
226

227
## Types
228

229
```python { .api }
230
class VersionInfo:
231
    """Version information structure"""
232
    def __init__(self):
233
        self.client_version: str        # Client version string
234
        self.server_version: str        # Server version string (if applicable)
235
        self.python_version: str        # Python version
236
        self.platform: str              # Operating system platform
237
        
238
class BenchmarkResults:
239
    """Benchmark operation results"""
240
    def __init__(self):
241
        self.create_time: float         # Time for create operations
242
        self.extract_time: float        # Time for extract operations  
243
        self.update_time: float         # Time for update operations
244
        self.delete_time: float         # Time for delete operations
245
        self.throughput: dict           # Throughput statistics
246
        
247
class LockInfo:
248
    """Repository lock information"""
249
    def __init__(self):
250
        self.exclusive: bool            # Exclusive lock held
251
        self.lock_id: str              # Lock identifier
252
        self.timestamp: str            # Lock acquisition time
253
        self.hostname: str             # Host holding the lock
254
        self.pid: int                  # Process ID holding the lock
255
```