-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathconfiguration.html
2061 lines (2061 loc) · 175 KB
/
configuration.html
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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>
<title>pgBackRest - Configuration Reference
</title><meta http-equiv="Content-Type" content="text/html;charset=utf-8"></meta>
<meta property="og:site_name" content="pgBackRest - Reliable PostgreSQL Backup & Restore"></meta>
<meta property="og:title" content="pgBackRest - Configuration Reference"></meta>
<meta property="og:type" content="website"></meta>
<link rel="icon" href="favicon.png" type="image/png"></link>
<meta property="og:image:type" content="image/png"></meta>
<meta property="og:image" content="http://www.pgbackrest.org/logo.png"></meta>
<meta name="description" content="The pgBackRest Configuration Reference details all configuration options."></meta>
<meta property="og:description" content="The pgBackRest Configuration Reference details all configuration options."></meta>
<link rel="stylesheet" href="default.css" type="text/css"></link>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-VKCRNV73H1"></script>
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','G-VKCRNV73H1');</script>
</head><body><div class="page-header"><div class="page-header-title">
pgBackRest
</div><div class="page-header-subtitle">
Configuration Reference
</div></div><div class="page-menu"><div class="menu-body"><div class="menu"><a class="menu-link" href="/">
Home
</a></div><div class="menu"><a class="menu-link" href="user-guide-index.html">
User Guides
</a></div><div class="menu"><a class="menu-link" href="release.html">
Releases
</a></div><div class="menu"><a class="menu-link" href="command.html">
Commands
</a></div><div class="menu"><a class="menu-link" href="faq.html">
FAQ
</a></div><div class="menu"><a class="menu-link" href="metric.html">
Metrics
</a></div></div></div><div class="page-toc"><div class="page-toc-header"><div class="page-toc-title">
Table of Contents
</div></div><div class="page-toc-body"><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#introduction">
Introduction
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-archive">
Archive Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-archive/option-archive-async">
Asynchronous Archiving Option (<span class="id">--archive-async</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-archive/option-archive-get-queue-max">
Maximum Archive Get Queue Size Option (<span class="id">--archive-get-queue-max</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-archive/option-archive-missing-retry">
Retry Missing WAL Segment Option (<span class="id">--archive-missing-retry</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-archive/option-archive-push-queue-max">
Maximum Archive Push Queue Size Option (<span class="id">--archive-push-queue-max</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-archive/option-archive-timeout">
Archive Timeout Option (<span class="id">--archive-timeout</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-backup">
Backup Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-annotation">
Backup Annotation Option (<span class="id">--annotation</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-archive-check">
Check Archive Option (<span class="id">--archive-check</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-archive-copy">
Copy Archive Option (<span class="id">--archive-copy</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-archive-mode-check">
Check Archive Mode Option (<span class="id">--archive-mode-check</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-backup-standby">
Backup from Standby Option (<span class="id">--backup-standby</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-checksum-page">
Page Checksums Option (<span class="id">--checksum-page</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-exclude">
Path/File Exclusions Option (<span class="id">--exclude</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-expire-auto">
Expire Auto Option (<span class="id">--expire-auto</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-manifest-save-threshold">
Manifest Save Threshold Option (<span class="id">--manifest-save-threshold</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-resume">
Resume Option (<span class="id">--resume</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-start-fast">
Start Fast Option (<span class="id">--start-fast</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-backup/option-stop-auto">
Stop Auto Option (<span class="id">--stop-auto</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-general">
General Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-buffer-size">
Buffer Size Option (<span class="id">--buffer-size</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-cmd">
pgBackRest Command Option (<span class="id">--cmd</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-cmd-ssh">
SSH Client Command Option (<span class="id">--cmd-ssh</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-compress">
Compress Option (<span class="id">--compress</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-compress-level">
Compress Level Option (<span class="id">--compress-level</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-compress-level-network">
Network Compress Level Option (<span class="id">--compress-level-network</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-compress-type">
Compress Type Option (<span class="id">--compress-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-db-timeout">
Database Timeout Option (<span class="id">--db-timeout</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-delta">
Delta Option (<span class="id">--delta</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-io-timeout">
I/O Timeout Option (<span class="id">--io-timeout</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-lock-path">
Lock Path Option (<span class="id">--lock-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-neutral-umask">
Neutral Umask Option (<span class="id">--neutral-umask</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-process-max">
Process Maximum Option (<span class="id">--process-max</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-protocol-timeout">
Protocol Timeout Option (<span class="id">--protocol-timeout</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-sck-keep-alive">
Keep Alive Option (<span class="id">--sck-keep-alive</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-spool-path">
Spool Path Option (<span class="id">--spool-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-tcp-keep-alive-count">
Keep Alive Count Option (<span class="id">--tcp-keep-alive-count</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-tcp-keep-alive-idle">
Keep Alive Idle Option (<span class="id">--tcp-keep-alive-idle</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-general/option-tcp-keep-alive-interval">
Keep Alive Interval Option (<span class="id">--tcp-keep-alive-interval</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-log">
Log Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-log/option-log-level-console">
Console Log Level Option (<span class="id">--log-level-console</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-log/option-log-level-file">
File Log Level Option (<span class="id">--log-level-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-log/option-log-level-stderr">
Std Error Log Level Option (<span class="id">--log-level-stderr</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-log/option-log-path">
Log Path Option (<span class="id">--log-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-log/option-log-subprocess">
Log Subprocesses Option (<span class="id">--log-subprocess</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-log/option-log-timestamp">
Log Timestamp Option (<span class="id">--log-timestamp</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-maintainer">
Maintainer Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-maintainer/option-archive-header-check">
Check WAL Headers Option (<span class="id">--archive-header-check</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-maintainer/option-page-header-check">
Page Header Check Option (<span class="id">--page-header-check</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-maintainer/option-pg-version-force">
Force PostgreSQL Version Option (<span class="id">--pg-version-force</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-repository">
Repository Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-azure-account">
Azure Repository Account Option (<span class="id">--repo-azure-account</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-azure-container">
Azure Repository Container Option (<span class="id">--repo-azure-container</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-azure-endpoint">
Azure Repository Endpoint Option (<span class="id">--repo-azure-endpoint</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-azure-key">
Azure Repository Key Option (<span class="id">--repo-azure-key</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-azure-key-type">
Azure Repository Key Type Option (<span class="id">--repo-azure-key-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-azure-uri-style">
Azure Repository URI Style Option (<span class="id">--repo-azure-uri-style</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-block">
Block Incremental Backup Option (<span class="id">--repo-block</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-bundle">
Repository Bundles Option (<span class="id">--repo-bundle</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-bundle-limit">
Repository Bundle Limit Option (<span class="id">--repo-bundle-limit</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-bundle-size">
Repository Bundle Size Option (<span class="id">--repo-bundle-size</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-cipher-pass">
Repository Cipher Passphrase Option (<span class="id">--repo-cipher-pass</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-cipher-type">
Repository Cipher Type Option (<span class="id">--repo-cipher-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-gcs-bucket">
GCS Repository Bucket Option (<span class="id">--repo-gcs-bucket</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-gcs-endpoint">
GCS Repository Endpoint Option (<span class="id">--repo-gcs-endpoint</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-gcs-key">
GCS Repository Key Option (<span class="id">--repo-gcs-key</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-gcs-key-type">
GCS Repository Key Type Option (<span class="id">--repo-gcs-key-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-gcs-user-project">
GCS Repository Project ID Option (<span class="id">--repo-gcs-user-project</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-hardlink">
Repository Hardlink Option (<span class="id">--repo-hardlink</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host">
Repository Host Option (<span class="id">--repo-host</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-ca-file">
Repository Host Certificate Authority File Option (<span class="id">--repo-host-ca-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-ca-path">
Repository Host Certificate Authority Path Option (<span class="id">--repo-host-ca-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-cert-file">
Repository Host Certificate File Option (<span class="id">--repo-host-cert-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-cmd">
Repository Host Command Option (<span class="id">--repo-host-cmd</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-config">
Repository Host Configuration Option (<span class="id">--repo-host-config</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-config-include-path">
Repository Host Configuration Include Path Option (<span class="id">--repo-host-config-include-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-config-path">
Repository Host Configuration Path Option (<span class="id">--repo-host-config-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-key-file">
Repository Host Key File Option (<span class="id">--repo-host-key-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-port">
Repository Host Port Option (<span class="id">--repo-host-port</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-type">
Repository Host Protocol Type Option (<span class="id">--repo-host-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-host-user">
Repository Host User Option (<span class="id">--repo-host-user</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-path">
Repository Path Option (<span class="id">--repo-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-retention-archive">
Archive Retention Option (<span class="id">--repo-retention-archive</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-retention-archive-type">
Archive Retention Type Option (<span class="id">--repo-retention-archive-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-retention-diff">
Differential Retention Option (<span class="id">--repo-retention-diff</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-retention-full">
Full Retention Option (<span class="id">--repo-retention-full</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-retention-full-type">
Full Retention Type Option (<span class="id">--repo-retention-full-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-retention-history">
Backup History Retention Option (<span class="id">--repo-retention-history</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-bucket">
S3 Repository Bucket Option (<span class="id">--repo-s3-bucket</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-endpoint">
S3 Repository Endpoint Option (<span class="id">--repo-s3-endpoint</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-key">
S3 Repository Access Key Option (<span class="id">--repo-s3-key</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-key-secret">
S3 Repository Secret Access Key Option (<span class="id">--repo-s3-key-secret</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-key-type">
S3 Repository Key Type Option (<span class="id">--repo-s3-key-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-kms-key-id">
S3 Repository KMS Key ID Option (<span class="id">--repo-s3-kms-key-id</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-region">
S3 Repository Region Option (<span class="id">--repo-s3-region</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-requester-pays">
S3 Repository Requestor Pays Option (<span class="id">--repo-s3-requester-pays</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-role">
S3 Repository Role Option (<span class="id">--repo-s3-role</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-sse-customer-key">
S3 Repository SSE Customer Key Option (<span class="id">--repo-s3-sse-customer-key</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-token">
S3 Repository Security Token Option (<span class="id">--repo-s3-token</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-s3-uri-style">
S3 Repository URI Style Option (<span class="id">--repo-s3-uri-style</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-host">
SFTP Repository Host Option (<span class="id">--repo-sftp-host</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-host-fingerprint">
SFTP Repository Host Fingerprint Option (<span class="id">--repo-sftp-host-fingerprint</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-host-key-check-type">
SFTP Host Key Check Type Option (<span class="id">--repo-sftp-host-key-check-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-host-key-hash-type">
SFTP Repository Host Key Hash Type Option (<span class="id">--repo-sftp-host-key-hash-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-host-port">
SFTP Repository Host Port Option (<span class="id">--repo-sftp-host-port</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-host-user">
SFTP Repository Host User Option (<span class="id">--repo-sftp-host-user</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-known-host">
SFTP Known Hosts File Option (<span class="id">--repo-sftp-known-host</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-private-key-file">
SFTP Repository Private Key File Option (<span class="id">--repo-sftp-private-key-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-private-key-passphrase">
SFTP Repository Private Key Passphrase Option (<span class="id">--repo-sftp-private-key-passphrase</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-sftp-public-key-file">
SFTP Repository Public Key File Option (<span class="id">--repo-sftp-public-key-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-ca-file">
Repository Storage CA File Option (<span class="id">--repo-storage-ca-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-ca-path">
Repository Storage TLS CA Path Option (<span class="id">--repo-storage-ca-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-host">
Repository Storage Host Option (<span class="id">--repo-storage-host</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-port">
Repository Storage Port Option (<span class="id">--repo-storage-port</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-tag">
Repository Storage Tag Option (<span class="id">--repo-storage-tag</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-upload-chunk-size">
Repository Storage Upload Chunk Size Option (<span class="id">--repo-storage-upload-chunk-size</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-storage-verify-tls">
Repository Storage Certificate Verify Option (<span class="id">--repo-storage-verify-tls</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-target-time">
Target Time for Repository Option (<span class="id">--repo-target-time</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-repository/option-repo-type">
Repository Type Option (<span class="id">--repo-type</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-restore">
Restore Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-archive-mode">
Archive Mode Option (<span class="id">--archive-mode</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-db-exclude">
Exclude Database Option (<span class="id">--db-exclude</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-db-include">
Include Database Option (<span class="id">--db-include</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-link-all">
Link All Option (<span class="id">--link-all</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-link-map">
Link Map Option (<span class="id">--link-map</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-recovery-option">
Recovery Option Option (<span class="id">--recovery-option</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-tablespace-map">
Tablespace Map Option (<span class="id">--tablespace-map</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-restore/option-tablespace-map-all">
Map All Tablespaces Option (<span class="id">--tablespace-map-all</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-server">
Server Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-server/option-tls-server-address">
TLS Server Address Option (<span class="id">--tls-server-address</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-server/option-tls-server-auth">
TLS Server Authorized Clients Option (<span class="id">--tls-server-auth</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-server/option-tls-server-ca-file">
TLS Server Certificate Authorities Option (<span class="id">--tls-server-ca-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-server/option-tls-server-cert-file">
TLS Server Certificate Option (<span class="id">--tls-server-cert-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-server/option-tls-server-key-file">
TLS Server Key Option (<span class="id">--tls-server-key-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-server/option-tls-server-port">
TLS Server Port Option (<span class="id">--tls-server-port</span>)
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#section-stanza">
Stanza Options
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-database">
PostgreSQL Database Option (<span class="id">--pg-database</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host">
PostgreSQL Host Option (<span class="id">--pg-host</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-ca-file">
PostgreSQL Host Certificate Authority File Option (<span class="id">--pg-host-ca-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-ca-path">
PostgreSQL Host Certificate Authority Path Option (<span class="id">--pg-host-ca-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-cert-file">
PostgreSQL Host Certificate File Option (<span class="id">--pg-host-cert-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-cmd">
PostgreSQL Host Command Option (<span class="id">--pg-host-cmd</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-config">
PostgreSQL Host Configuration Option (<span class="id">--pg-host-config</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-config-include-path">
PostgreSQL Host Configuration Include Path Option (<span class="id">--pg-host-config-include-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-config-path">
PostgreSQL Host Configuration Path Option (<span class="id">--pg-host-config-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-key-file">
PostgreSQL Host Key File Option (<span class="id">--pg-host-key-file</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-port">
PostgreSQL Host Port Option (<span class="id">--pg-host-port</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-type">
PostgreSQL Host Protocol Type Option (<span class="id">--pg-host-type</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-host-user">
PostgreSQL Host User Option (<span class="id">--pg-host-user</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-path">
PostgreSQL Path Option (<span class="id">--pg-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-port">
PostgreSQL Port Option (<span class="id">--pg-port</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-socket-path">
PostgreSQL Socket Path Option (<span class="id">--pg-socket-path</span>)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#section-stanza/option-pg-user">
PostgreSQL Database User Option (<span class="id">--pg-user</span>)
</a></div></div></div></div></div><div class="page-body"><div class="section1"><a id="introduction"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Introduction
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> can be used entirely with command-line parameters but a configuration file is more practical for installations that are complex or set a lot of options. The default location for the configuration file is <span class="file">/etc/pgbackrest/pgbackrest.conf</span>. If no file exists in that location then the old default of <span class="file">/etc/pgbackrest.conf</span> will be checked.
</div><div class="section-body-text">
The following option types are used:
</div><div class="section-body-text">
<b>String</b>: A text string, commonly an identifier, password, etc.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--stanza=demo</span><br/>Configuration file example: <span class="br-setting">repo1-cipher-pass=zWaf6XtpjIVZC5444yXB...</span>
</div><div class="section-body-text">
<b>Path</b>: Used to uniquely identify a location in a directory structure. Paths must begin with /, double // is not allowed, and no ending / is expected.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--repo1-path=/var/lib/pgbackrest</span><br/>Configuration file example: <span class="br-setting">repo1-path=/var/lib/pgbackrest</span>
</div><div class="section-body-text">
<b>Boolean</b>: Enables or disables the option. Only y/n are valid argument values.
</div><div class="section-body-text">
Command line examples: <span class="br-setting">--start-fast</span>, <span class="br-setting">--no-start-fast</span>, <span class="br-setting">--start-fast=y</span>, <span class="br-setting">--start-fast=n</span><br/>Configuration file examples: <span class="br-setting">start-fast=y</span>, <span class="br-setting">start-fast=n</span>
</div><div class="section-body-text">
<b>Integer</b>: Used for ports, retention/retry counts, parallel processes allowed, etc.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--compress-level=3</span><br/>Configuration file example: <span class="br-setting">pg1-port=5432</span>
</div><div class="section-body-text">
<b>Size</b>: Used for buffer sizes, disk usage, etc. Size can be specified in bytes (default) or KiB, MiB, GiB, TiB, or PiB where the multiplier is a power of 1024. For example, the case-insensitive value 5GiB (or 5GB, 5g) can be used instead of 5368709120. Fractional values such as 2.5GiB are not allowed, use 2560MiB instead.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--archive-get-queue-max=1GiB</span><br/>Configuration file example: <span class="br-setting">buffer-size=2MiB</span>
</div><div class="section-body-text">
<b>Time</b>: Time in seconds.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--io-timeout=90</span><br/>Configuration file example: <span class="br-setting">db-timeout=600</span>
</div><div class="section-body-text">
<b>List</b>: Option may be provided multiple times.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--db-exclude=db1 --db-exclude=db2 --db-exclude=db5</span><br/>Configuration file example, each on its own line: <span class="br-setting">db-exclude=db1 db-exclude=db2 db-exclude=db5</span>
</div><div class="section-body-text">
<b>Key/Value</b>: Option may be provided multiple times in the form <span class="id">key=value</span>.
</div><div class="section-body-text">
Command line example: <span class="br-setting">--tablespace-map=ts_01=/db/ts_01 --tablespace-map=ts_02=/db/ts_02</span><br/>Configuration file example, each on its own line: <span class="br-setting">tablespace-map=ts_01=/db/ts_01 tablespace-map=ts_02=/db/ts_02</span>
</div></div></div><div class="section1"><a id="section-archive"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Archive Options
</div></div><div class="section-body"><div class="section-body-text">
The <span class="br-setting">archive</span> section defines options for the <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span> commands.
</div><div class="section2"><a id="section-archive/option-archive-async"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Asynchronous Archiving Option (<span class="id">--archive-async</span>)
</div></div><div class="section-body"><div class="section-body-text">
Push/get WAL segments asynchronously.
</div><div class="section-body-text">
Enables asynchronous operation for the <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span> commands.
</div><div class="section-body-text">
Asynchronous operation is more efficient because it can reuse connections and take advantage of parallelism. See the <span class="br-option">spool-path</span>, <span class="br-option">archive-get-queue-max</span>, and <span class="br-option">archive-push-queue-max</span> options for more information.
</div>
<pre class="code-block">default: n
example: archive-async=y</pre>
</div></div><div class="section2"><a id="section-archive/option-archive-get-queue-max"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Maximum Archive Get Queue Size Option (<span class="id">--archive-get-queue-max</span>)
</div></div><div class="section-body"><div class="section-body-text">
Maximum size of the <span class="backrest">pgBackRest</span> archive-get queue.
</div><div class="section-body-text">
Specifies the maximum size of the <span class="cmd">archive-get</span> queue when <span class="br-option">archive-async</span> is enabled. The queue is stored in the <span class="br-option">spool-path</span> and is used to speed providing WAL to <span class="postgres">PostgreSQL</span>.
</div>
<pre class="code-block">default: 128MiB
allowed: 0B-4PiB
example: archive-get-queue-max=1GiB</pre>
</div></div><div class="section2"><a id="section-archive/option-archive-missing-retry"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Retry Missing WAL Segment Option (<span class="id">--archive-missing-retry</span>)
</div></div><div class="section-body"><div class="section-body-text">
Retry missing WAL segment
</div><div class="section-body-text">
Retry a WAL segment that was previously reported as missing by the <span class="cmd">archive-get</span> command when in asynchronous mode. This prevents notifications in the spool path from a prior restore from being used and possibly causing a recovery failure if consistency has not been reached.
</div><div class="section-body-text">
Disabling this option allows <span class="postgres">PostgreSQL</span> to more reliably recognize when the end of the WAL in the archive has been reached, which permits it to switch over to streaming from the primary. With retries enabled, a steady stream of WAL being archived will cause <span class="postgres">PostgreSQL</span> to continue getting WAL from the archive rather than switch to streaming.
</div><div class="section-body-text">
When disabling this option it is important to ensure that the spool path for the stanza is empty. The <span class="cmd">restore</span> command does this automatically if the spool path is configured at restore time. Otherwise, it is up to the user to ensure the spool path is empty.
</div>
<pre class="code-block">default: y
example: archive-missing-retry=n</pre>
</div></div><div class="section2"><a id="section-archive/option-archive-push-queue-max"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Maximum Archive Push Queue Size Option (<span class="id">--archive-push-queue-max</span>)
</div></div><div class="section-body"><div class="section-body-text">
Maximum size of the <span class="postgres">PostgreSQL</span> archive queue.
</div><div class="section-body-text">
After the limit is reached, the following will happen:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="backrest">pgBackRest</span> will notify <span class="postgres">PostgreSQL</span> that the WAL was successfully archived, then <b>DROP IT</b>.
</li><li class="list-unordered">
A warning will be output to the <span class="postgres">PostgreSQL</span> log.
</li></ul><div class="section-body-text">
If this occurs then the archive log stream will be interrupted and PITR will not be possible past that point. A new backup will be required to regain full restore capability.
</div><div class="section-body-text">
In asynchronous mode the entire queue will be dropped to prevent spurts of WAL getting through before the queue limit is exceeded again.
</div><div class="section-body-text">
The purpose of this feature is to prevent the log volume from filling up at which point <span class="postgres">PostgreSQL</span> will stop completely. Better to lose the backup than have <span class="postgres">PostgreSQL</span> go down.
</div>
<pre class="code-block">allowed: 0B-4PiB
example: archive-push-queue-max=1TiB</pre>
<div class="section-body-text">
Deprecated Name: archive-queue-max
</div></div></div><div class="section2"><a id="section-archive/option-archive-timeout"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Archive Timeout Option (<span class="id">--archive-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
Archive timeout.
</div><div class="section-body-text">
Set maximum time, in seconds, to wait for each WAL segment to reach the <span class="backrest">pgBackRest</span> archive repository. The timeout applies to the <span class="cmd">check</span> and <span class="cmd">backup</span> commands when waiting for WAL segments required for backup consistency to be archived.
</div>
<pre class="code-block">default: 1m
allowed: 100ms-1d
example: archive-timeout=30</pre>
</div></div></div></div><div class="section1"><a id="section-backup"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Backup Options
</div></div><div class="section-body"><div class="section-body-text">
The <span class="br-setting">backup</span> section defines settings related to backup.
</div><div class="section2"><a id="section-backup/option-annotation"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Backup Annotation Option (<span class="id">--annotation</span>)
</div></div><div class="section-body"><div class="section-body-text">
Annotate backup with user-defined key/value pairs.
</div><div class="section-body-text">
Users can attach informative key/value pairs to the backup. This option may be used multiple times to attach multiple annotations.
</div><div class="section-body-text">
Annotations are output by the <span class="cmd">info</span> command text output when a backup is specified with <span class="br-option">--set</span> and always appear in the JSON output.
</div>
<pre class="code-block">example: annotation=source="Sunday backup for website database"</pre>
</div></div><div class="section2"><a id="section-backup/option-archive-check"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Check Archive Option (<span class="id">--archive-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check that WAL segments are in the archive before backup completes.
</div><div class="section-body-text">
Checks that all WAL segments required to make the backup consistent are present in the WAL archive. It's a good idea to leave this as the default unless you are using another method for archiving.
</div><div class="section-body-text">
This option must be enabled if <span class="br-option">archive-copy</span> is enabled.
</div>
<pre class="code-block">default: y
example: archive-check=n</pre>
</div></div><div class="section2"><a id="section-backup/option-archive-copy"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Copy Archive Option (<span class="id">--archive-copy</span>)
</div></div><div class="section-body"><div class="section-body-text">
Copy WAL segments needed for consistency to the backup.
</div><div class="section-body-text">
This slightly paranoid option protects against corruption in the WAL segment archive by storing the WAL segments required for consistency directly in the backup. WAL segments are still stored in the archive so this option will use additional space.
</div><div class="section-body-text">
It is best if the <span class="cmd">archive-push</span> and <span class="cmd">backup</span> commands have the same <span class="br-setting">compress-type</span> (e.g. <span class="id">lz4</span>) when using this option. Otherwise, the WAL segments will need to be recompressed with the <span class="br-setting">compress-type</span> used by the backup, which can be fairly expensive depending on how much WAL was generated during the backup.
</div><div class="section-body-text">
On restore, the WAL segments will be present in <span class="path">pg_xlog/pg_wal</span> and <span class="postgres">PostgreSQL</span> will use them in preference to calling the <span class="id">restore_command</span>.
</div><div class="section-body-text">
The <span class="br-option">archive-check</span> option must be enabled if <span class="br-option">archive-copy</span> is enabled.
</div>
<pre class="code-block">default: n
example: archive-copy=y</pre>
</div></div><div class="section2"><a id="section-backup/option-archive-mode-check"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Check Archive Mode Option (<span class="id">--archive-mode-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check the <span class="postgres">PostgreSQL</span> <span class="br-setting">archive_mode</span> setting.
</div><div class="section-body-text">
Enabled by default, this option disallows <span class="postgres">PostgreSQL</span> <span class="br-setting">archive_mode=always</span>.
</div><div class="section-body-text">
WAL segments pushed from a standby server might be logically the same as WAL segments pushed from the primary but have different checksums. Disabling archiving from multiple sources is recommended to avoid conflicts.
</div><div class="admonition"><div class="caution">
CAUTION:
</div><div class="caution-text">
If this option is disabled then it is critical to ensure that only one archiver is writing to the repository via the <span class="cmd">archive-push</span> command.
</div></div>
<pre class="code-block">default: y
example: archive-mode-check=n</pre>
</div></div><div class="section2"><a id="section-backup/option-backup-standby"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Backup from Standby Option (<span class="id">--backup-standby</span>)
</div></div><div class="section-body"><div class="section-body-text">
Backup from the standby cluster.
</div><div class="section-body-text">
Enable backup from standby to reduce load on the primary cluster. This option requires that both the <span class="host">primary</span> and <span class="host">standby</span> hosts be configured.
</div><div class="section-body-text">
The following modes are supported:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">y</span> - Standby is required for backup.
</li><li class="list-unordered">
<span class="id">prefer</span> - Backup from standby if available otherwise backup from primary.
</li><li class="list-unordered">
<span class="id">n</span> - Backup from primary only.
</li></ul>
<pre class="code-block">default: n
example: backup-standby=y</pre>
</div></div><div class="section2"><a id="section-backup/option-checksum-page"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Page Checksums Option (<span class="id">--checksum-page</span>)
</div></div><div class="section-body"><div class="section-body-text">
Validate data page checksums.
</div><div class="section-body-text">
Directs <span class="backrest">pgBackRest</span> to validate all data page checksums while backing up a cluster. This option is automatically enabled when data page checksums are enabled on the cluster.
</div><div class="section-body-text">
Failures in checksum validation will not abort a backup. Rather, warnings will be emitted in the log (and to the console with default settings) and the list of invalid pages will be stored in the backup manifest.
</div>
<pre class="code-block">example: checksum-page=n</pre>
</div></div><div class="section2"><a id="section-backup/option-exclude"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Path/File Exclusions Option (<span class="id">--exclude</span>)
</div></div><div class="section-body"><div class="section-body-text">
Exclude paths/files from the backup.
</div><div class="section-body-text">
All exclusions are relative to <span class="path">$PGDATA</span>. If the exclusion ends with / then only files in the specified directory will be excluded, e.g. <span class="br-option">--exclude=junk/</span> will exclude all files in the <span class="path">$PGDATA/junk</span> directory but include the directory itself. If the exclusion does not end with / then the file may match the exclusion exactly or match with / appended to the exclusion, e.g. <span class="br-option">--exclude=junk</span> will exclude the <span class="path">$PGDATA/junk</span> directory and all the files it contains.
</div><div class="section-body-text">
<b>Be careful using this feature -- it is very easy to exclude something critical that will make the backup inconsistent. Be sure to test your restores!</b>
</div><div class="section-body-text">
All excluded files will be logged at <span class="id">info</span> level along with the exclusion rule. Be sure to audit the list of excluded files to ensure nothing unexpected is being excluded.
</div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
Exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will be <i>removed</i> on delta restore.
</div></div><div class="section-body-text">
This option should not be used to exclude <span class="postgres">PostgreSQL</span> logs from a backup. Logs can be moved out of the <span class="id">PGDATA</span> directory using the <span class="postgres">PostgreSQL</span> <span class="br-setting">log_directory</span> setting, which has the benefit of allowing logs to be preserved after a restore.
</div><div class="section-body-text">
Multiple exclusions may be specified on the command-line or in a configuration file.
</div>
<pre class="code-block">example: exclude=junk/</pre>
</div></div><div class="section2"><a id="section-backup/option-expire-auto"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Expire Auto Option (<span class="id">--expire-auto</span>)
</div></div><div class="section-body"><div class="section-body-text">
Automatically run the <span class="cmd">expire</span> command after a successful backup.
</div><div class="section-body-text">
The setting is enabled by default. Use caution when disabling this option as doing so will result in retaining all backups and archives indefinitely, which could cause your repository to run out of space. The <span class="cmd">expire</span> command will need to be run regularly to prevent this from happening.
</div>
<pre class="code-block">default: y
example: expire-auto=y</pre>
</div></div><div class="section2"><a id="section-backup/option-manifest-save-threshold"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Manifest Save Threshold Option (<span class="id">--manifest-save-threshold</span>)
</div></div><div class="section-body"><div class="section-body-text">
Manifest save threshold during backup.
</div><div class="section-body-text">
Defines how often the manifest will be saved during a backup. Saving the manifest is important because it stores the checksums and allows the resume function to work efficiently. The actual threshold used is 1% of the backup size or <span class="br-setting">manifest-save-threshold</span>, whichever is greater.
</div>
<pre class="code-block">default: 1GiB
allowed: 1B-1TiB
example: manifest-save-threshold=8GiB</pre>
</div></div><div class="section2"><a id="section-backup/option-resume"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Resume Option (<span class="id">--resume</span>)
</div></div><div class="section-body"><div class="section-body-text">
Allow resume of failed backup.
</div><div class="section-body-text">
Defines whether the resume feature is enabled. Resume can greatly reduce the amount of time required to run a backup after a previous backup of the same type has failed. It adds complexity, however, so it may be desirable to disable in environments that do not require the feature.
</div>
<pre class="code-block">default: y
example: resume=n</pre>
</div></div><div class="section2"><a id="section-backup/option-start-fast"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Start Fast Option (<span class="id">--start-fast</span>)
</div></div><div class="section-body"><div class="section-body-text">
Force a checkpoint to start backup quickly.
</div><div class="section-body-text">
Forces a checkpoint (by passing <span class="id">y</span> to the <span class="id">fast</span> parameter of the backup start function) so the backup begins immediately. Otherwise the backup will start after the next regular checkpoint.
</div>
<pre class="code-block">default: n
example: start-fast=y</pre>
</div></div><div class="section2"><a id="section-backup/option-stop-auto"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Stop Auto Option (<span class="id">--stop-auto</span>)
</div></div><div class="section-body"><div class="section-body-text">
Stop prior failed backup on new backup.
</div><div class="section-body-text">
This will only be done if an exclusive advisory lock can be acquired to demonstrate that the prior failed backup process has really stopped.
</div><div class="section-body-text">
This feature is not supported for <span class="postgres">PostgreSQL</span> >= <span class="id">9.6</span> since backups are run in non-exclusive mode.
</div><div class="section-body-text">
The setting is disabled by default because it assumes that <span class="backrest">pgBackRest</span> is the only process doing exclusive online backups. It depends on an advisory lock that only <span class="backrest">pgBackRest</span> sets so it may abort other processes that do exclusive online backups. Note that <span class="cmd">base_backup</span> and <span class="cmd">pg_dump</span> are safe to use with this setting because they do not call <span class="id">pg_start_backup()</span> so are not exclusive.
</div>
<pre class="code-block">default: n
example: stop-auto=y</pre>
</div></div></div></div><div class="section1"><a id="section-general"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
General Options
</div></div><div class="section-body"><div class="section-body-text">
The <span class="br-setting">general</span> section defines options that are common for many commands.
</div><div class="section2"><a id="section-general/option-buffer-size"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Buffer Size Option (<span class="id">--buffer-size</span>)
</div></div><div class="section-body"><div class="section-body-text">
Buffer size for I/O operations.
</div><div class="section-body-text">
Buffer size used for copy, compress, encrypt, and other operations. The number of buffers used depends on options and each operation may use additional memory, e.g. <span class="id">gz</span> compression may use an additional 256KiB of memory.
</div><div class="section-body-text">
Allowed values are <span class="id">16KiB</span>, <span class="id">32KiB</span>, <span class="id">64KiB</span>, <span class="id">128KiB</span>, <span class="id">256KiB</span>, <span class="id">512KiB</span>, <span class="id">1MiB</span>, <span class="id">2MiB</span>, <span class="id">4MiB</span>, <span class="id">8MiB</span>, and <span class="id">16MiB</span>.
</div>
<pre class="code-block">default: 1MiB
example: buffer-size=2MiB</pre>
</div></div><div class="section2"><a id="section-general/option-cmd"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
pgBackRest Command Option (<span class="id">--cmd</span>)
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> command.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> may generate a command string, e.g. when the <span class="cmd">restore</span> command generates the <span class="pg-setting">restore_command</span> setting. The command used to run the <span class="backrest">pgBackRest</span> process will be used in this case unless the <span class="br-option">cmd</span> option is provided.
</div><div class="admonition"><div class="caution">
CAUTION:
</div><div class="caution-text">
Wrapping the <span class="backrest">pgBackRest</span> command may cause unpredictable behavior and is not recommended.
</div></div>
<pre class="code-block">example: cmd=/var/lib/pgsql/bin/pgbackrest_wrapper.sh</pre>
</div></div><div class="section2"><a id="section-general/option-cmd-ssh"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
SSH Client Command Option (<span class="id">--cmd-ssh</span>)
</div></div><div class="section-body"><div class="section-body-text">
SSH client command.
</div><div class="section-body-text">
Use a specific SSH client command when an alternate is desired or the <span class="file">ssh</span> command is not in $PATH.
</div>
<pre class="code-block">default: ssh
example: cmd-ssh=/usr/bin/ssh</pre>
</div></div><div class="section2"><a id="section-general/option-compress"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Compress Option (<span class="id">--compress</span>)
</div></div><div class="section-body"><div class="section-body-text">
Use file compression.
</div><div class="section-body-text">
Backup files are compatible with command-line compression tools.
</div><div class="section-body-text">
This option is now deprecated. The <span class="br-setting">compress-type</span> option should be used instead.
</div>
<pre class="code-block">default: y
example: compress=n</pre>
</div></div><div class="section2"><a id="section-general/option-compress-level"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Compress Level Option (<span class="id">--compress-level</span>)
</div></div><div class="section-body"><div class="section-body-text">
File compression level.
</div><div class="section-body-text">
Sets the level to be used for file compression when <span class="br-setting">compress-type</span> does not equal <span class="id">none</span> or <span class="br-setting">compress=y</span> (deprecated).
</div><div class="section-body-text">
The following are the defaults levels based on <span class="br-setting">compress-type</span> when <span class="br-setting">compress-level</span> is not specified:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">bz2</span> - 9
</li><li class="list-unordered">
<span class="id">gz</span> - 6
</li><li class="list-unordered">
<span class="id">lz4</span> - 1
</li><li class="list-unordered">
<span class="id">zst</span> - 3
</li></ul>
<pre class="code-block">example: compress-level=9</pre>
</div></div><div class="section2"><a id="section-general/option-compress-level-network"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Network Compress Level Option (<span class="id">--compress-level-network</span>)
</div></div><div class="section-body"><div class="section-body-text">
Network compression level.
</div><div class="section-body-text">
Sets the network compression level when <span class="br-setting">compress-type=none</span> and the command is not run on the same host as the repository. Compression is used to reduce network traffic. When <span class="br-setting">compress-type</span> does not equal <span class="id">none</span> the <span class="br-setting">compress-level-network</span> setting is ignored and <span class="br-setting">compress-level</span> is used instead so that the file is only compressed once.
</div>
<pre class="code-block">default: 1
allowed: -5-12
example: compress-level-network=1</pre>
</div></div><div class="section2"><a id="section-general/option-compress-type"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Compress Type Option (<span class="id">--compress-type</span>)
</div></div><div class="section-body"><div class="section-body-text">
File compression type.
</div><div class="section-body-text">
The following compression types are supported:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">none</span> - no compression
</li><li class="list-unordered">
<span class="id">bz2</span> - bzip2 compression format
</li><li class="list-unordered">
<span class="id">gz</span> - gzip compression format
</li><li class="list-unordered">
<span class="id">lz4</span> - lz4 compression format (not available on all platforms)
</li><li class="list-unordered">
<span class="id">zst</span> - Zstandard compression format (not available on all platforms)
</li></ul>
<pre class="code-block">default: gz
example: compress-type=none</pre>
</div></div><div class="section2"><a id="section-general/option-db-timeout"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Database Timeout Option (<span class="id">--db-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
Database query timeout.
</div><div class="section-body-text">
Sets the timeout, in seconds, for queries against the database. This includes the backup start/stop functions which can each take a substantial amount of time. Because of this the timeout should be kept high unless you know that these functions will return quickly (i.e. if you have set <span class="br-setting">start-fast=y</span> and you know that the database cluster will not generate many WAL segments during the backup).
</div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
The <span class="br-option">db-timeout</span> option must be less than the <span class="br-option">protocol-timeout</span> option.
</div></div>
<pre class="code-block">default: 30m
allowed: 100ms-7d
example: db-timeout=600</pre>
</div></div><div class="section2"><a id="section-general/option-delta"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Delta Option (<span class="id">--delta</span>)
</div></div><div class="section-body"><div class="section-body-text">
Restore or backup using checksums.
</div><div class="section-body-text">
During a restore, by default the <span class="postgres">PostgreSQL</span> data and tablespace directories are expected to be present but empty. This option performs a delta restore using checksums.
</div><div class="section-body-text">
During a backup, this option will use checksums instead of the timestamps to determine if files will be copied.
</div>
<pre class="code-block">default: n
example: delta=y</pre>
</div></div><div class="section2"><a id="section-general/option-io-timeout"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
I/O Timeout Option (<span class="id">--io-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
I/O timeout.
</div><div class="section-body-text">
Timeout, in seconds, used for connections and read/write operations.
</div><div class="section-body-text">
Note that the entire read/write operation does not need to complete within this timeout but <i>some</i> progress must be made, even if it is only a single byte.
</div>
<pre class="code-block">default: 1m
allowed: 100ms-1h
example: io-timeout=120</pre>
</div></div><div class="section2"><a id="section-general/option-lock-path"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Lock Path Option (<span class="id">--lock-path</span>)
</div></div><div class="section-body"><div class="section-body-text">
Path where lock files are stored.
</div><div class="section-body-text">
The lock path provides a location for <span class="backrest">pgBackRest</span> to create lock files to prevent conflicting operations from being run concurrently.
</div>
<pre class="code-block">default: /tmp/pgbackrest
example: lock-path=/backup/db/lock</pre>
</div></div><div class="section2"><a id="section-general/option-neutral-umask"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Neutral Umask Option (<span class="id">--neutral-umask</span>)
</div></div><div class="section-body"><div class="section-body-text">
Use a neutral umask.
</div><div class="section-body-text">
Sets the umask to 0000 so modes in the repository are created in a sensible way. The default directory mode is 0750 and default file mode is 0640. The lock and log directories set the directory and file mode to 0770 and 0660 respectively.
</div><div class="section-body-text">
To use the executing user's umask instead specify <span class="br-setting">neutral-umask=n</span> in the config file or <span class="br-setting">--no-neutral-umask</span> on the command line.
</div>
<pre class="code-block">default: y
example: neutral-umask=n</pre>
</div></div><div class="section2"><a id="section-general/option-process-max"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Process Maximum Option (<span class="id">--process-max</span>)
</div></div><div class="section-body"><div class="section-body-text">
Max processes to use for compress/transfer.
</div><div class="section-body-text">
Each process will perform compression and transfer to make the command run faster, but don't set <span class="br-setting">process-max</span> so high that it impacts database performance.
</div>
<pre class="code-block">default: 1
allowed: 1-999
example: process-max=4</pre>
</div></div><div class="section2"><a id="section-general/option-protocol-timeout"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Protocol Timeout Option (<span class="id">--protocol-timeout</span>)
</div></div><div class="section-body"><div class="section-body-text">
Protocol timeout.
</div><div class="section-body-text">
Sets the timeout, in seconds, that the local or remote process will wait for a new message to be received on the protocol layer. This prevents processes from waiting indefinitely for a message.
</div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
The <span class="br-option">protocol-timeout</span> option must be greater than the <span class="br-option">db-timeout</span> option.
</div></div>
<pre class="code-block">default: 31m
allowed: 100ms-7d
example: protocol-timeout=630</pre>
</div></div><div class="section2"><a id="section-general/option-sck-keep-alive"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Keep Alive Option (<span class="id">--sck-keep-alive</span>)
</div></div><div class="section-body"><div class="section-body-text">
Keep-alive enable.
</div><div class="section-body-text">
Enables keep-alive messages on socket connections.
</div>
<pre class="code-block">default: y
example: sck-keep-alive=n</pre>
</div></div><div class="section2"><a id="section-general/option-spool-path"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Spool Path Option (<span class="id">--spool-path</span>)
</div></div><div class="section-body"><div class="section-body-text">
Path where transient data is stored.
</div><div class="section-body-text">
This path is used to store data for the asynchronous <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span> command.
</div><div class="section-body-text">
The asynchronous <span class="cmd">archive-push</span> command writes acknowledgements into the spool path when it has successfully stored WAL in the archive (and errors on failure) so the foreground process can quickly notify <span class="postgres">PostgreSQL</span>. Acknowledgement files are very small (zero on success and a few hundred bytes on error).
</div><div class="section-body-text">
The asynchronous <span class="cmd">archive-get</span> command queues WAL in the spool path so it can be provided very quickly when <span class="postgres">PostgreSQL</span> requests it. Moving files to <span class="postgres">PostgreSQL</span> is most efficient when the spool path is on the same filesystem as <span class="path">pg_xlog</span>/<span class="path">pg_wal</span>. However, it is not recommended to place the spool path <i>within</i> the <span class="path">pg_xlog</span>/<span class="path">pg_wal</span> directory as this may cause issues for <span class="postgres">PostgreSQL</span> utilities such as <span class="file">pg_rewind</span>.
</div><div class="section-body-text">
The data stored in the spool path is not strictly temporary since it can and should survive a reboot. However, loss of the data in the spool path is not a problem. <span class="backrest">pgBackRest</span> will simply recheck each WAL segment to ensure it is safely archived for <span class="cmd">archive-push</span> and rebuild the queue for <span class="cmd">archive-get</span>.
</div><div class="section-body-text">
The spool path is intended to be located on a local Posix-compatible filesystem, not a remote filesystem such as <span class="host">NFS</span> or <span class="host">CIFS</span>.
</div>
<pre class="code-block">default: /var/spool/pgbackrest
example: spool-path=/backup/db/spool</pre>
</div></div><div class="section2"><a id="section-general/option-tcp-keep-alive-count"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Keep Alive Count Option (<span class="id">--tcp-keep-alive-count</span>)
</div></div><div class="section-body"><div class="section-body-text">
Keep-alive count.
</div><div class="section-body-text">
Specifies the number of TCP keep-alive messages that can be lost before the connection is considered dead.
</div><div class="section-body-text">
This option is available on systems that support the <span class="id">TCP_KEEPCNT</span> socket option.
</div>
<pre class="code-block">allowed: 1-32
example: tcp-keep-alive-count=3</pre>
</div></div><div class="section2"><a id="section-general/option-tcp-keep-alive-idle"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Keep Alive Idle Option (<span class="id">--tcp-keep-alive-idle</span>)
</div></div><div class="section-body"><div class="section-body-text">
Keep-alive idle time.
</div><div class="section-body-text">
Specifies the amount of time (in seconds) with no network activity after which the operating system should send a TCP keep-alive message.
</div><div class="section-body-text">
This option is available on systems that support the <span class="id">TCP_KEEPIDLE</span> socket option.
</div>
<pre class="code-block">allowed: 1-3600
example: tcp-keep-alive-idle=60</pre>
</div></div><div class="section2"><a id="section-general/option-tcp-keep-alive-interval"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Keep Alive Interval Option (<span class="id">--tcp-keep-alive-interval</span>)
</div></div><div class="section-body"><div class="section-body-text">
Keep-alive interval time.
</div><div class="section-body-text">
Specifies the amount of time (in seconds) after which a TCP keep-alive message that has not been acknowledged should be retransmitted.
</div><div class="section-body-text">
This option is available on systems that support the <span class="id">TCP_KEEPINTVL</span> socket option.
</div>
<pre class="code-block">allowed: 1-900
example: tcp-keep-alive-interval=30</pre>
</div></div></div></div><div class="section1"><a id="section-log"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Log Options
</div></div><div class="section-body"><div class="section-body-text">
The <span class="br-setting">log</span> section defines logging-related settings.
</div><div class="admonition"><div class="caution">
CAUTION:
</div><div class="caution-text">
Trace-level logging may expose secrets such as keys and passwords. Use with caution!
</div></div><div class="section2"><a id="section-log/option-log-level-console"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Console Log Level Option (<span class="id">--log-level-console</span>)
</div></div><div class="section-body"><div class="section-body-text">
Level for console logging.
</div><div class="section-body-text">
The following log levels are supported:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">off</span> - No logging at all (not recommended)
</li><li class="list-unordered">
<span class="id">error</span> - Log only errors
</li><li class="list-unordered">
<span class="id">warn</span> - Log warnings and errors
</li><li class="list-unordered">
<span class="id">info</span> - Log info, warnings, and errors
</li><li class="list-unordered">
<span class="id">detail</span> - Log detail, info, warnings, and errors
</li><li class="list-unordered">
<span class="id">debug</span> - Log debug, detail, info, warnings, and errors
</li><li class="list-unordered">
<span class="id">trace</span> - Log trace (very verbose debugging), debug, info, warnings, and errors
</li></ul>
<pre class="code-block">default: warn
example: log-level-console=error</pre>
</div></div><div class="section2"><a id="section-log/option-log-level-file"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
File Log Level Option (<span class="id">--log-level-file</span>)
</div></div><div class="section-body"><div class="section-body-text">
Level for file logging.
</div><div class="section-body-text">
The following log levels are supported:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">off</span> - No logging at all (not recommended)
</li><li class="list-unordered">
<span class="id">error</span> - Log only errors
</li><li class="list-unordered">
<span class="id">warn</span> - Log warnings and errors
</li><li class="list-unordered">
<span class="id">info</span> - Log info, warnings, and errors
</li><li class="list-unordered">
<span class="id">detail</span> - Log detail, info, warnings, and errors
</li><li class="list-unordered">
<span class="id">debug</span> - Log debug, detail, info, warnings, and errors
</li><li class="list-unordered">
<span class="id">trace</span> - Log trace (very verbose debugging), debug, info, warnings, and errors
</li></ul>
<pre class="code-block">default: info
example: log-level-file=debug</pre>
</div></div><div class="section2"><a id="section-log/option-log-level-stderr"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Std Error Log Level Option (<span class="id">--log-level-stderr</span>)
</div></div><div class="section-body"><div class="section-body-text">
Level for stderr logging.
</div><div class="section-body-text">
Specifies which log levels will output to <span class="id">stderr</span> rather than <span class="id">stdout</span> (specified by <span class="br-option">log-level-console</span>). The timestamp and process will not be output to <span class="id">stderr</span>.
</div><div class="section-body-text">
The following log levels are supported:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="id">off</span> - No logging at all (not recommended)
</li><li class="list-unordered">
<span class="id">error</span> - Log only errors
</li><li class="list-unordered">
<span class="id">warn</span> - Log warnings and errors
</li><li class="list-unordered">
<span class="id">info</span> - Log info, warnings, and errors
</li><li class="list-unordered">
<span class="id">detail</span> - Log detail, info, warnings, and errors
</li><li class="list-unordered">
<span class="id">debug</span> - Log debug, detail, info, warnings, and errors
</li><li class="list-unordered">
<span class="id">trace</span> - Log trace (very verbose debugging), debug, info, warnings, and errors
</li></ul>
<pre class="code-block">default: off
example: log-level-stderr=error</pre>
</div></div><div class="section2"><a id="section-log/option-log-path"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Log Path Option (<span class="id">--log-path</span>)
</div></div><div class="section-body"><div class="section-body-text">
Path where log files are stored.
</div><div class="section-body-text">
The log path provides a location for <span class="backrest">pgBackRest</span> to store log files. Note that if <span class="br-setting">log-level-file=off</span> then no log path is required.
</div>
<pre class="code-block">default: /var/log/pgbackrest
example: log-path=/backup/db/log</pre>
</div></div><div class="section2"><a id="section-log/option-log-subprocess"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Log Subprocesses Option (<span class="id">--log-subprocess</span>)
</div></div><div class="section-body"><div class="section-body-text">
Enable logging in subprocesses.
</div><div class="section-body-text">
Enable file logging for any subprocesses created by this process using the log level specified by <span class="br-option">log-level-file</span>.
</div>
<pre class="code-block">default: n
example: log-subprocess=y</pre>
</div></div><div class="section2"><a id="section-log/option-log-timestamp"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Log Timestamp Option (<span class="id">--log-timestamp</span>)
</div></div><div class="section-body"><div class="section-body-text">
Enable timestamp in logging.
</div><div class="section-body-text">
Enables the timestamp in console and file logging. This option is disabled in special situations such as generating documentation.
</div>
<pre class="code-block">default: y
example: log-timestamp=n</pre>
</div></div></div></div><div class="section1"><a id="section-maintainer"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Maintainer Options
</div></div><div class="section-body"><div class="section-body-text">
Maintainer options are intended to support <span class="postgres">PostgreSQL</span> forks. The proper settings should be determined by the fork maintainer and then communicated to users of the fork.
</div><div class="admonition"><div class="warning">
WARNING:
</div><div class="warning-text">
Improper use of these options may lead to unexpected behavior or data corruption.
</div></div><div class="section-body-text">
It is the responsibility of the fork maintainer to test <span class="backrest">pgBackRest</span> with the required options. <span class="backrest">pgBackRest</span> does not guarantee compatibility with any fork.
</div><div class="section2"><a id="section-maintainer/option-archive-header-check"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Check WAL Headers Option (<span class="id">--archive-header-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check PostgreSQL version/id in WAL headers.
</div><div class="section-body-text">
Enabled by default, this option checks the WAL header against the <span class="postgres">PostgreSQL</span> version and system identifier to ensure that the WAL is being copied to the correct stanza. This is in addition to checking <span class="file">pg_control</span> against the stanza and verifying that WAL is being copied from the same <span class="postgres">PostgreSQL</span> data directory where <span class="file">pg_control</span> is located.
</div><div class="section-body-text">
Therefore, disabling this check is fairly safe but should only be done when needed, e.g. if the WAL is encrypted.
</div>
<pre class="code-block">default: y
example: archive-header-check=n</pre>
</div></div><div class="section2"><a id="section-maintainer/option-page-header-check"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Page Header Check Option (<span class="id">--page-header-check</span>)
</div></div><div class="section-body"><div class="section-body-text">
Check PostgreSQL page headers.
</div><div class="section-body-text">
Enabled by default, this option adds page header checks.
</div><div class="section-body-text">
Disabling this option should be avoided except when necessary, e.g. if pages are encrypted.
</div>
<pre class="code-block">default: y
example: page-header-check=n</pre>
</div></div><div class="section2"><a id="section-maintainer/option-pg-version-force"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Force PostgreSQL Version Option (<span class="id">--pg-version-force</span>)
</div></div><div class="section-body"><div class="section-body-text">
Force <span class="postgres">PostgreSQL</span> version.
</div><div class="section-body-text">
The specified <span class="postgres">PostgreSQL</span> version will be used instead of the version automatically detected by reading <span class="file">pg_control</span> or WAL headers. This is mainly useful for <span class="postgres">PostgreSQL</span> forks or development versions where those values are different from the release version. The version reported by <span class="postgres">PostgreSQL</span> via `server_version_num` must match the forced version.
</div><div class="admonition"><div class="warning">
WARNING:
</div><div class="warning-text">
Be cautious when using this option because <span class="file">pg_control</span> and WAL headers will still be read with the expected format for the specified version, i.e. the format from the official open-source version of <span class="postgres">PostgreSQL</span>. If the fork or development version changes the format of the fields that <span class="backrest">pgBackRest</span> depends on it will lead to unexpected behavior. In general, this option will only work as expected if the fork adds all custom struct members <i>after</i> the standard <span class="postgres">PostgreSQL</span> members.
</div></div>
<pre class="code-block">example: pg-version-force=15</pre>
</div></div></div></div><div class="section1"><a id="section-repository"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Repository Options
</div></div><div class="section-body"><div class="section-body-text">
The <span class="br-setting">repository</span> section defines options used to configure the repository.
</div><div class="section-body-text">
<b>Indexing</b>: All <span class="br-setting">repo-</span> options are indexed to allow for configuring multiple repositories. For example, a single repository is configured with the <span class="br-setting">repo1-path</span>, <span class="br-setting">repo1-host</span>, etc. options. If there is more than one repository configured and the <span class="br-option">--repo</span> option is not specified for a command, the repositories will be acted upon in highest priority order (e.g. repo1 then repo2).
</div><div class="section-body-text">
The <span class="br-setting">repo-retention-*</span> options define how long backups will be retained. Expiration only occurs when the count of complete backups exceeds the allowed retention. In other words, if <span class="br-setting">repo1-retention-full-type</span> is set to <span class="br-setting">count</span> (default) and <span class="br-setting">repo1-retention-full</span> is set to 2, then there must be 3 complete backups before the oldest will be expired. If <span class="br-setting">repo1-retention-full-type</span> is set to <span class="br-setting">time</span> then <span class="br-setting">repo1-retention-full</span> represents days so there must be at least that many days worth of full backups before expiration can occur. Make sure you always have enough space for retention + 1 backups.
</div><div class="section2"><a id="section-repository/option-repo-azure-account"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Azure Repository Account Option (<span class="id">--repo-azure-account</span>)
</div></div><div class="section-body"><div class="section-body-text">
Azure repository account.
</div><div class="section-body-text">
Azure account used to store the repository.
</div>
<pre class="code-block">example: repo1-azure-account=pg-backup</pre>
</div></div><div class="section2"><a id="section-repository/option-repo-azure-container"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">