0
# System Administration
1
2
Complete Vault administration interface providing initialization, seal management, policy administration, audit logging, cluster operations, and system monitoring. HVAC's system backend offers comprehensive administrative control for enterprise Vault deployments.
3
4
## Capabilities
5
6
### Vault Initialization and Unsealing
7
8
Bootstrap new Vault instances and manage seal/unseal operations for startup and emergency procedures.
9
10
```python { .api }
11
class Init:
12
def read_init_status(self) -> dict: ...
13
def is_initialized(self) -> bool: ...
14
def initialize(
15
self,
16
secret_shares: int = 5,
17
secret_threshold: int = 3,
18
pgp_keys: list = None,
19
root_token_pgp_key: str = None,
20
stored_shares: int = None, # Enterprise HSM
21
recovery_shares: int = None, # Enterprise HSM
22
recovery_threshold: int = None, # Enterprise HSM
23
recovery_pgp_keys: list = None # Enterprise HSM
24
) -> dict: ...
25
26
class Seal:
27
def read_seal_status(self) -> dict: ...
28
def is_sealed(self) -> bool: ...
29
def seal(self) -> dict: ...
30
def submit_unseal_key(
31
self,
32
key: str,
33
reset: bool = False,
34
migrate: bool = None
35
) -> dict: ...
36
def submit_unseal_keys(self, keys: list) -> dict: ...
37
```
38
39
### Authentication Method Management
40
41
Configure and manage authentication backends for user and machine identity verification.
42
43
```python { .api }
44
class Auth:
45
def list_auth_methods(self) -> dict: ...
46
def enable_auth_method(
47
self,
48
method_type: str,
49
description: str = None,
50
config: dict = None,
51
plugin_name: str = None,
52
local: bool = None, # Enterprise replication
53
path: str = None
54
) -> None: ...
55
def disable_auth_method(self, path: str) -> None: ...
56
def read_auth_method_tuning(self, path: str) -> dict: ...
57
def tune_auth_method(
58
self,
59
path: str,
60
default_lease_ttl: str = None,
61
max_lease_ttl: str = None,
62
description: str = None,
63
audit_non_hmac_request_keys: list = None,
64
audit_non_hmac_response_keys: list = None,
65
listing_visibility: str = None,
66
passthrough_request_headers: list = None,
67
allowed_response_headers: list = None,
68
token_type: str = None
69
) -> None: ...
70
```
71
72
### Secrets Engine Management
73
74
Mount, configure, and manage secrets engines for different secret types and credential systems.
75
76
```python { .api }
77
class Mount:
78
def list_mounted_secrets_engines(self) -> dict: ...
79
def enable_secrets_engine(
80
self,
81
backend_type: str,
82
description: str = None,
83
config: dict = None,
84
options: dict = None,
85
local: bool = None, # Enterprise replication
86
seal_wrap: bool = None, # Enterprise seal wrapping
87
path: str = None
88
) -> None: ...
89
def disable_secrets_engine(self, path: str) -> None: ...
90
def read_mount_configuration(self, path: str) -> dict: ...
91
def tune_mount_configuration(
92
self,
93
path: str,
94
default_lease_ttl: str = None,
95
max_lease_ttl: str = None,
96
description: str = None,
97
audit_non_hmac_request_keys: list = None,
98
audit_non_hmac_response_keys: list = None,
99
listing_visibility: str = None,
100
passthrough_request_headers: list = None,
101
allowed_response_headers: list = None
102
) -> None: ...
103
def move_backend(self, from_path: str, to_path: str) -> None: ...
104
def retrieve_mount_option(self, mount_point: str, option_name: str) -> dict: ...
105
```
106
107
### Access Control Policy Management
108
109
Create and manage ACL policies and Enterprise governance policies for fine-grained access control.
110
111
```python { .api }
112
class Policy:
113
def list_policies(self) -> dict: ...
114
def read_policy(self, name: str, pretty_print: bool = False) -> dict: ...
115
def create_or_update_policy(
116
self,
117
name: str,
118
policy: str | dict,
119
pretty_print: bool = False
120
) -> None: ...
121
def delete_policy(self, name: str) -> None: ...
122
123
class Policies:
124
# ACL Policies
125
def list_acl_policies(self) -> dict: ...
126
def read_acl_policy(self, name: str) -> dict: ...
127
def create_or_update_acl_policy(
128
self,
129
name: str,
130
policy: str | dict
131
) -> None: ...
132
def delete_acl_policy(self, name: str) -> None: ...
133
134
# Role Governing Policies (Enterprise)
135
def list_rgp_policies(self) -> dict: ...
136
def read_rgp_policy(self, name: str) -> dict: ...
137
def create_or_update_rgp_policy(
138
self,
139
name: str,
140
policy: str,
141
enforcement_level: str = "hard-mandatory" # advisory, soft-mandatory, hard-mandatory
142
) -> None: ...
143
def delete_rgp_policy(self, name: str) -> None: ...
144
145
# Endpoint Governing Policies (Enterprise)
146
def list_egp_policies(self) -> dict: ...
147
def read_egp_policy(self, name: str) -> dict: ...
148
def create_or_update_egp_policy(
149
self,
150
name: str,
151
policy: str,
152
paths: list,
153
enforcement_level: str = "hard-mandatory"
154
) -> None: ...
155
def delete_egp_policies(self, name: str) -> None: ...
156
```
157
158
### Audit Logging Configuration
159
160
Configure comprehensive audit logging for compliance and security monitoring.
161
162
```python { .api }
163
class Audit:
164
def list_enabled_audit_devices(self) -> dict: ...
165
def enable_audit_device(
166
self,
167
device_type: str, # file, syslog, socket
168
description: str = None,
169
options: dict = None,
170
path: str = None,
171
local: bool = None # Enterprise replication
172
) -> None: ...
173
def disable_audit_device(self, path: str) -> None: ...
174
def calculate_hash(
175
self,
176
path: str,
177
input_to_hash: str
178
) -> dict: ...
179
```
180
181
### Lease Management
182
183
Monitor and manage secret leases for credential lifecycle and cleanup operations.
184
185
```python { .api }
186
class Lease:
187
def read_lease(self, lease_id: str) -> dict: ...
188
def list_leases(self, prefix: str) -> dict: ...
189
def renew_lease(
190
self,
191
lease_id: str,
192
increment: int = None
193
) -> dict: ...
194
def revoke_lease(self, lease_id: str) -> None: ...
195
def revoke_prefix(
196
self,
197
prefix: str,
198
sync: bool = False
199
) -> None: ...
200
def revoke_force(
201
self,
202
prefix: str,
203
sync: bool = False
204
) -> None: ...
205
```
206
207
### Key Management and Rotation
208
209
Manage Vault's encryption keys, root token generation, and rekeying operations.
210
211
```python { .api }
212
class Key:
213
# Encryption Key Management
214
def get_encryption_key_status(self) -> dict: ...
215
def rotate_encryption_key(self) -> None: ...
216
217
# Root Token Generation
218
def read_root_generation_progress(self) -> dict: ...
219
def start_root_token_generation(
220
self,
221
key: str = None,
222
pgp_key: str = None
223
) -> dict: ...
224
def generate_root(
225
self,
226
key: str,
227
nonce: str
228
) -> dict: ...
229
def cancel_root_generation(self) -> dict: ...
230
231
# Rekeying Operations
232
def read_rekey_progress(self) -> dict: ...
233
def start_rekey(
234
self,
235
secret_shares: int = None,
236
secret_threshold: int = None,
237
pgp_keys: list = None,
238
backup: bool = None,
239
require_verification: bool = None
240
) -> dict: ...
241
def rekey(
242
self,
243
key: str,
244
nonce: str
245
) -> dict: ...
246
def rekey_multi(
247
self,
248
keys: list,
249
nonce: str
250
) -> dict: ...
251
def cancel_rekey(self) -> dict: ...
252
def read_backup_keys(self) -> dict: ...
253
def rekey_verify(
254
self,
255
key: str,
256
nonce: str
257
) -> dict: ...
258
def rekey_verify_multi(
259
self,
260
keys: list,
261
nonce: str
262
) -> dict: ...
263
```
264
265
### Health Monitoring and High Availability
266
267
Monitor Vault health status and manage high availability cluster operations.
268
269
```python { .api }
270
class Health:
271
def read_health_status(
272
self,
273
standby_ok: bool = None,
274
active_code: int = 200,
275
standby_code: int = 429,
276
dr_secondary_code: int = 472,
277
performance_standby_code: int = 473,
278
sealed_code: int = 503,
279
uninit_code: int = 501,
280
method: str = "GET"
281
) -> dict: ...
282
283
class Leader:
284
def read_leader_status(self) -> dict: ...
285
def step_down(self) -> None: ...
286
```
287
288
### Capability Verification
289
290
Verify token permissions and capabilities for access control testing.
291
292
```python { .api }
293
class Capabilities:
294
def get_capabilities(
295
self,
296
paths: list,
297
token: str = None,
298
accessor: str = None
299
) -> dict: ...
300
```
301
302
### Enterprise Features
303
304
Advanced enterprise features for multi-tenancy, rate limiting, and integrated storage.
305
306
```python { .api }
307
class Namespace:
308
def create_namespace(
309
self,
310
path: str
311
) -> None: ...
312
def list_namespaces(self) -> dict: ...
313
def delete_namespace(self, path: str) -> None: ...
314
315
class Quota:
316
def list_quotas(self) -> dict: ...
317
def read_quota(self, name: str) -> dict: ...
318
def create_or_update_quota(
319
self,
320
name: str,
321
rate: float,
322
path: str = "",
323
interval: str = "1s",
324
block_interval: str = "10s",
325
inheritable: bool = None
326
) -> None: ...
327
def delete_quota(self, name: str) -> None: ...
328
329
class Raft:
330
# Cluster Management
331
def join_raft_cluster(
332
self,
333
leader_api_addr: str,
334
leader_ca_cert: str = None,
335
leader_client_cert: str = None,
336
leader_client_key: str = None,
337
retry: bool = None,
338
non_voter: bool = None
339
) -> dict: ...
340
def read_raft_config(self) -> dict: ...
341
def remove_raft_node(self, server_id: str) -> None: ...
342
343
# Snapshot Operations
344
def take_raft_snapshot(self) -> bytes: ...
345
def restore_raft_snapshot(self, snapshot: bytes) -> None: ...
346
def force_restore_raft_snapshot(self, snapshot: bytes) -> None: ...
347
348
# Auto-Snapshot Configuration
349
def list_raft_auto_snapshot_configs(self) -> dict: ...
350
def create_or_update_raft_auto_snapshot_config(
351
self,
352
name: str,
353
interval: str,
354
retain: int,
355
path_prefix: str,
356
storage_type: str, # aws-s3, azure-blob, google-gcs, local
357
**kwargs # Storage-specific configuration
358
) -> None: ...
359
def delete_raft_auto_snapshot_config(self, name: str) -> None: ...
360
361
class Wrapping:
362
def wrap(
363
self,
364
payload: dict,
365
ttl: int = 300
366
) -> dict: ...
367
def unwrap(self, token: str) -> dict: ...
368
```
369
370
## Usage Examples
371
372
### Initial Vault Setup
373
374
```python
375
import hvac
376
377
# Connect to uninitialized Vault
378
client = hvac.Client(url='https://vault.example.com:8200')
379
380
# Check initialization status
381
if not client.sys.init.is_initialized():
382
# Initialize Vault with 5 key shares, 2 required for unsealing
383
init_response = client.sys.init.initialize(
384
secret_shares=5,
385
secret_threshold=2
386
)
387
388
# Store unseal keys and root token securely
389
unseal_keys = init_response['keys']
390
root_token = init_response['root_token']
391
392
print(f"Vault initialized. Root token: {root_token}")
393
print(f"Unseal keys: {unseal_keys}")
394
395
# Check seal status and unseal if needed
396
seal_status = client.sys.seal.read_seal_status()
397
if seal_status['sealed']:
398
# Unseal with minimum threshold keys
399
client.sys.seal.submit_unseal_keys(unseal_keys[:2])
400
print("Vault unsealed successfully")
401
402
# Set root token for administrative operations
403
client.token = root_token
404
```
405
406
### Authentication Method Configuration
407
408
```python
409
# Enable username/password authentication
410
client.sys.auth.enable_auth_method(
411
method_type='userpass',
412
path='userpass',
413
description='Username/password authentication for users'
414
)
415
416
# Configure auth method settings
417
client.sys.auth.tune_auth_method(
418
path='userpass',
419
default_lease_ttl='1h',
420
max_lease_ttl='24h',
421
token_type='default'
422
)
423
424
# Enable AWS authentication for EC2 instances
425
client.sys.auth.enable_auth_method(
426
method_type='aws',
427
path='aws-ec2',
428
description='AWS EC2 instance authentication',
429
config={
430
'default_lease_ttl': '1h',
431
'max_lease_ttl': '12h'
432
}
433
)
434
435
# List all enabled auth methods
436
auth_methods = client.sys.auth.list_auth_methods()
437
for path, config in auth_methods['data'].items():
438
print(f"Auth method: {path} ({config['type']})")
439
```
440
441
### Secrets Engine Management
442
443
```python
444
# Enable KV v2 secrets engine
445
client.sys.mount.enable_secrets_engine(
446
backend_type='kv',
447
path='secret',
448
options={'version': '2'},
449
description='Application secrets storage'
450
)
451
452
# Enable database secrets engine for dynamic credentials
453
client.sys.mount.enable_secrets_engine(
454
backend_type='database',
455
path='database',
456
description='Dynamic database credentials'
457
)
458
459
# Tune secrets engine settings
460
client.sys.mount.tune_mount_configuration(
461
path='database',
462
default_lease_ttl='1h',
463
max_lease_ttl='12h'
464
)
465
466
# List all mounted secrets engines
467
mounts = client.sys.mount.list_mounted_secrets_engines()
468
for path, config in mounts['data'].items():
469
print(f"Secrets engine: {path} ({config['type']})")
470
```
471
472
### Policy Management
473
474
```python
475
# Create application policy
476
app_policy = """
477
path "secret/data/myapp/*" {
478
capabilities = ["create", "read", "update", "delete", "list"]
479
}
480
481
path "database/creds/readonly" {
482
capabilities = ["read"]
483
}
484
485
path "auth/token/renew-self" {
486
capabilities = ["update"]
487
}
488
"""
489
490
client.sys.policy.create_or_update_policy(
491
name='myapp-policy',
492
policy=app_policy
493
)
494
495
# Create read-only policy
496
readonly_policy = """
497
path "secret/data/*" {
498
capabilities = ["read", "list"]
499
}
500
"""
501
502
client.sys.policy.create_or_update_policy(
503
name='readonly-policy',
504
policy=readonly_policy
505
)
506
507
# List all policies
508
policies = client.sys.policy.list_policies()
509
print(f"Available policies: {policies['data']['policies']}")
510
```
511
512
### Audit Configuration
513
514
```python
515
# Enable file audit logging
516
client.sys.audit.enable_audit_device(
517
device_type='file',
518
path='file-audit',
519
options={
520
'file_path': '/var/log/vault/audit.log',
521
'log_raw': False
522
},
523
description='File-based audit logging'
524
)
525
526
# Enable syslog audit (redundant logging)
527
client.sys.audit.enable_audit_device(
528
device_type='syslog',
529
path='syslog-audit',
530
options={
531
'facility': 'AUTH',
532
'tag': 'vault'
533
},
534
description='Syslog audit logging'
535
)
536
537
# List enabled audit devices
538
audit_devices = client.sys.audit.list_enabled_audit_devices()
539
for path, config in audit_devices['data'].items():
540
print(f"Audit device: {path} ({config['type']})")
541
```
542
543
### Health Monitoring
544
545
```python
546
# Check Vault health for load balancer
547
health = client.sys.health.read_health_status(
548
standby_ok=True, # Accept standby nodes as healthy
549
active_code=200, # Active node returns 200
550
standby_code=200 # Standby node returns 200 (not 429)
551
)
552
553
print(f"Vault cluster ID: {health['cluster_id']}")
554
print(f"Version: {health['version']}")
555
print(f"Sealed: {health['sealed']}")
556
print(f"Standby: {health['standby']}")
557
558
# Check leader status for HA clusters
559
leader_status = client.sys.leader.read_leader_status()
560
print(f"HA enabled: {leader_status['ha_enabled']}")
561
if leader_status['ha_enabled']:
562
print(f"Is leader: {leader_status['is_self']}")
563
print(f"Leader address: {leader_status['leader_address']}")
564
```
565
566
### Advanced Key Management
567
568
```python
569
# Rotate the encryption key (automated background process)
570
client.sys.key.rotate_encryption_key()
571
print("Encryption key rotation initiated")
572
573
# Check key status
574
key_status = client.sys.key.get_encryption_key_status()
575
print(f"Key term: {key_status['term']}")
576
print(f"Install time: {key_status['install_time']}")
577
578
# Emergency root token generation (requires unseal keys)
579
# Start the process
580
root_gen_progress = client.sys.key.start_root_token_generation()
581
nonce = root_gen_progress['nonce']
582
583
# Submit unseal keys
584
for key in unseal_keys[:2]: # Submit threshold number of keys
585
result = client.sys.key.generate_root(key=key, nonce=nonce)
586
587
if result['complete']:
588
encoded_token = result['encoded_token']
589
# Decode the token (implementation depends on OTP used)
590
print(f"New root token generated: {encoded_token}")
591
```
592
593
### Cluster Operations (Raft Storage)
594
595
```python
596
# Check Raft cluster configuration
597
raft_config = client.sys.raft.read_raft_config()
598
for server in raft_config['data']['config']['servers']:
599
print(f"Node ID: {server['node_id']}, Address: {server['address']}")
600
601
# Configure automated snapshots
602
client.sys.raft.create_or_update_raft_auto_snapshot_config(
603
name='daily-backup',
604
interval='24h',
605
retain=7, # Keep 7 snapshots
606
path_prefix='vault-backup/',
607
storage_type='aws-s3',
608
aws_s3_bucket='vault-backups',
609
aws_s3_region='us-east-1'
610
)
611
612
# List auto-snapshot configurations
613
snapshot_configs = client.sys.raft.list_raft_auto_snapshot_configs()
614
print(f"Auto-snapshot configs: {list(snapshot_configs['data']['keys'])}")
615
```