o +ke@sddlZddlZzMddlZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlZddlZddlZddlZddlZddlZddlZddlmZmZddlmZddlmZmZddlmZddlmZm Z eZddl!Z!ddl"m#Z#dd l"m$Z$dd l%m&Z&dd l'm(Z(m)Z)m*Z*m+Z+m,Z,dd l'm-Z-m.Z.m/Z/m0Z0m1Z1dd l'm2Z2m3Z3m4Z4m5Z5ddl'm6Z6ddl7m8Z8m9Z9m:Z:ddl;Tddlm?Z?m@Z@mAZAmBZBmCZCmDZDddlEmFZFddl$mGZGmHZHmIZImJZJddl$mKZKmLZLmMZMddl$mNZNmOZOmPZPmQZQmRZRddl$mSZSmTZTmUZUmVZVmWZWddl$mXZXmYZYmZZZddl$m[Z[m\Z\m]Z]m^Z^ddl$m_Z_m`Z`maZambZbmcZcddl$mdZdmeZemfZfmgZgddl$mhZhmiZiddl$mjZjmkZkddl$mlZlmmZmddl$mnZndd l$moZodd!l$mpZpmqZqdd"l$mrZrmsZsmtZtmuZumvZvdd#l$mwZwdd$l$mxZxmyZymzZzm{Z{dd%l$m|Z|dd&l$m}Z}dd'l$m~Z~mZdd(l$mZdd)l$mZmZdd*l$mZmZmZdd+l$mZdd,l$mZdd-l$mZmZmZdd.l$mZdd/l$mZmZdd0l$mZdd1l$mZdd2lmZmZdd3lmZdd4lmZmZmZmZdd5lmZdd6lmZmZdd7lmZmZmZdd8lmZmZdd9lmZmZmZdd:lmZmZmZmZmZdd;lmZddd?Zd@ZeedAreejej_dBdCZ E E dYdFdGZdHdIZdJdKZdLdMZGdNdOdOejZGdPdQdQZdRdSZdTdUZdVdWZedXkreƃdSdS)ZN) unhexlifyhexlify)contextmanager)datetime timedelta) TextIOWrapper) create_logger setup_logging) __version__)helpers)crc32)ArchiveArchiveCheckerArchiveRecreater Statistics is_special) BackupError BackupOSError backup_ioOsOpenstat_update_check)FilesystemObjectProcessorsTarfileObjectProcessorsMetadataCollectorChunksProcessor)has_link)Cache assert_secureSecurityManager)*)CompressionSpec) key_creatorkey_argument_namestam_required_file tam_requiredRepoKey PassphraseKey) KeyManager) EXIT_SUCCESS EXIT_WARNING EXIT_ERROREXIT_SIGNAL_BASE)ErrorNoManifestErrorset_ec)positive_int_validatorlocation_validatorarchivename_validator ChunkerParamsLocation) PrefixSpecGlobSpec CommentSpec SortBySpecFilesCacheMode) BaseFormatter ItemFormatterArchiveFormatter)format_timedeltaformat_file_sizeparse_file_sizeformat_archive) safe_encoderemove_surrogates bin_to_hexprepare_dump_dict eval_escapes)interval prune_within prune_splitPRUNING_PATTERNS) timestamputcnow) get_cache_diros_stat)ManifestAI_HUMAN_SORT_KEYS) hardlinkable) StableDict) check_pythoncheck_extension_modules) dir_is_taggedis_slow_msgpackis_supported_msgpackyessysinfo) log_multi)signal_handlerraising_signal_handlerSigHupSigTerm)ErrorIgnoringTextIOWrapper)ProgressIndicatorPercent)basic_json_data json_print)replace_placeholders)ChunkIteratorFileWrappernormalize_chunker_params)popen_with_error_handlingprepare_subprocess_envcreate_filter_process) dash_open)umount) flags_dirflags_special_follow flags_special)msgpack)sig_int ignore_sigint)iter_separated)get_tar_filter)BorgJsonEncoder safe_decode)rst_to_terminal)ArgparsePatternActionArgparseExcludeFileActionArgparsePatternFileActionparse_exclude_pattern)PatternMatcher)Item ArchiveItem) get_flagsget_process_idSyncFile)uid2user gid2group)RepositoryServerRemoteRepositorycache_if_remote) RepositoryLIST_SCAN_LIMITTAG_PUT TAG_DELETE TAG_COMMIT)selftest)AtticRepositoryUpgraderBorgRepositoryUpgraderzZEXIT_ERROR is not 2, as expected - fix assert AND exception handler right above this line.zN Original size Compressed size Deduplicated sizezCUsing a pure-python msgpack! This will result in lower performance.fully_trusted_filtercs<t|tr t|St|ttfrtfdd|DS|S)zSIf bool is passed, return it. If str is passed, retrieve named attribute from args.c3s|]}t|VqdSN)getattr.0itemargs1usr/lib/python3.10/site-packages/borg/archiver.py szargument..) isinstancestrrlisttupleany)rZ str_or_boolrrrargumentns  rFTc sxssrdurtdtturtdndur%tdtr*tj|f dd} | S)u Method decorator for subcommand-handling methods: do_XYZ(self, args, repository, …) If a parameter (where allowed) is a str the attribute named of args is used instead. :param fake: (str or bool) use None instead of repository, don't do anything else :param create: create repository :param lock: lock repository :param exclusive: (str or bool) lock repository exclusively (for writing) :param manifest: load manifest and key, pass them as keyword arguments :param cache: open cache, pass it as keyword argument (implies manifest) :param secure: do assert_secure after loading manifest :param compatibility: mandatory if not create and (manifest or cache), specifies mandatory feature categories to check Nz=with_repository decorator used without compatibility argumentzFwith_repository decorator compatibility argument must be of type tuplezFwith_repository called with compatibility argument but would not checkc s,t f dd}|S)Nc st|d}|j}t|dd}t|dd}t|dd}t|Ar-||fddi|S|jdkrEt|t||j||||d}nt|jt||j||||d }|s]rt |\|d <|d <d |vrt|j j |d _ rt ||d |jrt||d |d t|d d|jt|dtt|ddt|ddd} ||f|| d|WdWdS1swYn||fd|i|WdSWddS1swYdS)Nlock append_onlyF storage_quotamake_parent_dirs repositoryZssh)create exclusive lock_waitrrrr)rrrrrrrmanifestkey compressionprogressfiles_cache_modeconsider_part_filesiec)rr cache_moderr)rcache)rlocationrprotorZ omit_archiverrpathrNloadrZ compressorrrZFILES_CACHE_MODE_DISABLED) selfrkwargsrrrrrrZcache_) _lockr compatibilityrrfake invert_fakermethodsecurerrwrappersN        "z3with_repository..decorator..wrapper functoolswrapsrr rrrrrrrrrrr decorators  z"with_repository..decorator)AssertionErrortyperreprrNNO_OPERATION_CHECK) rrrrrrrrrrrrrwith_repositoryws   #rcstfdd}|S)Ncsxt||||jjt|ddt|ddpt|ddt|ddt|dd|d|j|j|jd }||f||||d |S) N numeric_idsF nobsdflagsnoflagsnoaclsnoxattrsr)rrrrrrlog_jsonr)rrrarchive)rrrrgetrrr)rrrrrrrrrrrs    zwith_archive..wrapperrrrrr with_archives rcCs&t|}|tdkrtd||S)N10Mz3quota is too small (%s). At least 10M are required.)r?argparseArgumentTypeError)rparsedrrrparse_storage_quotas rcCs.dD]}t||d}|dur|Sqtd)N)func fallback_funcfallback2_funcz"expected func attributes not found)r Exception)rnamerrrrget_funcs  rc@seZdZdZdddZdS) Highlanderz(make sure some option is only given onceNcCs2t||jd|jkrt|dt||j|dS)NzThere can be only one.)rdestdefaultrZ ArgumentErrorsetattr)rparser namespacevaluesZ option_stringrrr__call__s zHighlander.__call__r)__name__ __module__ __qualname____doc__rrrrrrsrc@speZdZdddZddZddZdd Zed d Zd d Z e ddddddZ e dddddZ e e jjfdddZe dddddddZe dddddddZe dddd Zd!d"Ze d#de jjfd$dd%d&Zd'd(Zd)d*Zed+d,Ze e jjfded-d.Ze e jjfded/d0Zd1d2Ze e jjfded3d4Ze dde jjfd5ed6d7Z d8d9Z!e dddd:d;Z"dd?Z$d@dAZ%e e jjfddBdCZ&dDdEZ'e e jjfddFdGZ(dHdIZ)dJdKZ*e de jjfdLdMdNZ+dOdPZ,dQdRZ-e de jj.fdSdTdUZ/e dVddddWddXdYZ0e dde jjfdZd[d\Z1e dde jjfdZd]d^Z2d_d`Z3e dddadbdcZ4e dddadddeZ5e ddddfdgZ6dhdiZ7e e j8ddjdkZ9e e j8ddldmZ:e e j8ddndoZ;e dddpdqZe e j8ddvdwZ?e dddadxdyZ@e dddadzd{ZAe ddde j8d|d}d~ZBe dddaddZCddZDe dddddZEeFGZHeIJdeHd<eIJdeHd<eIJdeHd<ddZKddZLeLZMddZNGdddZOddZPddZQdddZRddZSddZTddZUddZVdS)ArchiverNcCs t|_||_||_t|_dSr)r) exit_coderprogtime monotoniclast_checkpoint)rrrrrr__init__szArchiver.__init__cG$|r||p|}t|_t|dSr)r+rloggererrorrmsgrrrr print_errorzArchiver.print_errorcGrr)r*rrwarningrrrr print_warningrzArchiver.print_warningcCst|jr4|dur6|jdus||jvr8|jr&ttd|t|dtjddSt d d|t|dSdSdSdS)NZ file_status)rstatusrfileborg.output.listz%1s %s) output_list output_filterrprintjsondumpsrBsysstderrlogging getLoggerinfo)rrrrrrprint_file_statuss"  zArchiver.print_file_statuscCst}|||||Sr)ry add_inclexclZadd_includepaths)Zinclexcl_patternsZ include_pathsmatcherrrr build_matcher s  zArchiver.build_matchercCs t|j|j|j|jdtS)z@Start in server mode. This command is usually not used manually.)restrict_to_pathsrestrict_to_repositoriesrr)rr r rrserver)rrrrrdo_serveszArchiver.do_serveTF)rrrc Cs|j}td|zt||}Wnttfy$|tYSwt ||}||_ | |j ddt |||ddWdn1sJwY|jrft|}t|dtdt||jdkrptd |jS) zInitialize an empty repositoryzInitializing repository at "%s"Fcompact)Zwarn_if_unencryptedNwa By default repositories initialized with this version will produce security errors if written to with an older version (up to and including Borg 1.0.8). If you want to use these older versions, you can disable the check by running: borg upgrade --disable-tam %s See https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability for details about the security implications. plaintexta) IMPORTANT: you will need both KEY AND PASSPHRASE to access this repo! If you used a repokey mode, the key is stored in the repo, but you should back it up separately. Use "borg key export" to export the key, optionally in printable format. Write down the passphrase. Store both at safe place(s). )rcanonical_pathrrr"EOFErrorKeyboardInterruptdestroyr*rNrwritecommitrr%r$openclosershlexquoteNAMEr)rrrrrrtam_filerrrdo_inits6    zArchiver.do_init)rrc Cs|jrd}t|ddddddstS|jr+t|j|j|j|jdu|j fr+| d tS|jr8|j r8| d tS|j rE|jsE| d tS|j sU|j |j|j|j d sUtS|jdur`|jd |_ |jstj ||j|jj|j|j|jptd|j |j|jd stStS)zCheck repository consistencyzThis is a potentially dangerous function. check --repair might lead to data loss (for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL! Type 'YES' if you understand this and want to continue: Aborting.Invalid answer, aborting.YESFZ!BORG_CHECK_I_KNOW_WHAT_I_AM_DOINGZ false_msgZ invalid_msgZtruishretryZenv_var_overrideNze--repository-only contradicts --first, --last, --glob-archives, --prefix and --verify-data arguments.z0--repair does not allow --max-duration argument.z9--repository-only is required for --max-duration support.)repair save_space max_durationr ts)r'rfirstlastsort_byglob verify_datar()r'rWr+ repo_onlyrr/r+r,prefix glob_archivesrr) archives_onlycheckr(r*rrrr-r))rrrrrrrdo_checkAs<         zArchiver.do_check)rcCsFt|ds tdtS|tdt|dr!td|tS)z%Change repository key file passphrasechange_passphrasez?This repository is not encrypted, cannot change the passphrase. Key updatedfind_keyzKey location: %s)hasattrrr+r6rrr8r)rrrrrrrrdo_change_passphrasehs   zArchiver.do_change_passphrase)rrrrcCs|t|}||jr||jt Sz|jr ||jWt S||jWt Sty=| d|jdt YSw)z$Export the repository key for backup'z!' must be a file, not a directory) r(Z load_keyblobpaperZexport_paperkeyrqrZ export_qrexportIsADirectoryErrorrr+r)rrrmanagerrrr do_key_exportus   zArchiver.do_key_exportcCs~t|}|jr|jr|dtS||t S|js"|dtS|jdkr8tj|js8|d|jtS||t S)z%Import the repository key from backupz.with --paper import from file is not supportedz&input file to import key from expected-zinput file does not exist: ) r(r=rrr+Zimport_paperkeyosexistsZimport_keyfiler)rArrr do_key_imports     zArchiver.do_key_import)rcCsd|tj}t||}t|}||_|j|_|j |_ |j |_ |j |_ |j |_ | tdtS)zMigrate passphrase -> repokeyr7)rrN MANIFEST_IDr'detectr&targetidZ repository_idZenc_keyZ enc_hmac_keyZid_keyZ chunk_seedr6rrr))rrrZ manifest_dataZkey_oldZkey_newrrrdo_migrate_to_repokeys   zArchiver.do_migrate_to_repokeyc s.fdd}tdd}dtjvrddg}ngd}|D]x\}}}}||j|||} ||j| \} } } } Wd n1sAwY||d }t|}|rTd nd }d }t|d||| |||| ft|d||| |||| ft|d||| |||| ft|d||| |||| fqdS)z4Benchmark Create, Read, Update, Delete for archives.c s|d}d}t}d|d|d|g}t}||}|dks'Jd||d|g}d|dg} || krLdksOJJt}d||d |g}t}||} d|d g} || krdksJJt}d d |dg}t}||} |dksJt}d|dg}t}||} |dksJ|| | | fS) Nz::borg-benchmark-crudz--compression=nonerz--files-cache=disabled1r2delete3extract --dry-run)rr do_create parse_args do_delete do_extract) reporrrZt_startrcZt_end dt_createZrc1Zrc2 dt_update dt_extract dt_deleterrrmeasurement_runs6    z3Archiver.do_benchmark_crud..measurement_runc sszatj|d}t||rdn|ttkr ttd|nd|}t|D]/}tj|d|}|s7|nt|}t |dd }| |Wdn1sRwYq(|VWt |dSt |w)Nzborg-test-datazfile_%dT)binary) rErjoinmakedirslenzeros memoryviewrangeurandomr~rshutilrmtree) rcountsizerandomZz_buffifnamedatafdrrr test_filess ,  z.Archiver.do_benchmark_crud..test_filesZ_BORG_BENCHMARK_CRUD_TEST)zZ-TESTrrF)zR-TESTrrT))zZ-BIG F)zR-BIGrrrsT)zZ-MEDIUM@BF)zR-MEDIUMrtruT)zZ-SMALL'rvF)zR-SMALLrvrvTNg.Arlzall-zeroz-%s-%-10s %9.2f MB/s (%d * %s %s files: %.2fs)CRUDr)rrEenvironrrrr>r)rrr^rqtestsrrjrkrlrrYrZr[r\Z total_size_MBZfile_size_formattedcontentfmtrr]rdo_benchmark_cruds* "      zArchiver.do_benchmark_cruddry_run)rrrc stddjfdd}j_j_jp"j_j_j_j _ j t }t }tdjjst||jjjjjdi}t||jj|djjj jjj||jjd} t j jjpjjjjj!d} t"||| j#| j$jd d } t%| ||| j&| j#jjj'jjj(d } || || Wd j)S1swYj)S|d d d j)S) zCreate new archiveTfallbackcst}ztt}||j|jfWn tyYnwjj s>ztjj }||j|jfWn ty=Ynwt dj rЈj}j}j}j}szUztdd} tjjtj| td} Wnttfy} zd| jWYd} ~ WSd} ~ ww|j||| j|||d} | } | dkrdjd| jWSWnty} zd || jWYd} ~ Sd} ~ wwd }  | |nj!s׈j"rj#durt$j#nd }j!rztdd} tjjtj| td} Wnttfy} zd| jWYd} ~ Sd} ~ ww| j}nt%j&j'}t(|d d }t)||D]f}tj *|}z-t+dt,|dddd}Wdn 1sLwYj-|dd|||j.d} Wntt/fy~} z0d || d} WYd} ~ nd} ~ ww| dkr0d| | |q+j!r| } | dkrdjd| jSnjD]}|d krj}j}j}j}sz|j||t%j&j'|||d} Wnty} zd} 0d || WYd} ~ nd} ~ wwd }  | |qtj *|}zHt+dt,|dddd}Wdn 1swYj1r'|jnd}j2|dd||j3j4j5||j.d ||j|jfWqtt/fyg} z0d || WYd} ~ qd} ~ wwsƈj6rv|j7j8dd|j7|j77_7t9rddS|j:j;jt?|d|iddSt@tAtB|tAtCtB|j7tB|tAtDEdddSdSdS)NzProcessing files ...Tsystem)stdoutenv preexec_fnzFailed to execute command: %s)rrrpmodeusergrouprz Command %r exited with status %d%s: %srD surrogateescape)errorsstatFr parent_fdrfollow_symlinksrrrstfsor read_specialrErw&%s: file changed while we backed it up rrrrrr exclude_cachesexclude_if_presentkeep_exclude_tags skip_inodes restrict_devrrfinalGot Ctrl-C / SIGINT.commentrJrrextraborg.output.statsr)FsetrErrLaddst_inost_devOSErrorrhostrrdebugcontent_from_command stdin_name stdin_mode stdin_user stdin_grouprf subprocessPopenpathsPIPEroFileNotFoundErrorPermissionErrorrrZ process_piperwaitrrpaths_from_commandpaths_from_stdinZpaths_delimiterrErstdinbufferrrpnormpathrrM _process_anyrrrone_file_system _rec_walkrrrrstats show_progressrnsaverrJrrar`rYDASHESr STATS_HEADERrr)rrrrrrrrrrprocerrXZ paths_sepZpipe_binpiperrrrr rrr create_inners                        z(Archiver.do_create..create_innerzCreating archive at "%s")rrZpermit_adhoc_cacherr) rrcheckpoint_intervalrnoatimenoctimerchunker_paramsstartstart_monotonicrr)rrrrrr nobirthtimeFrradd_itemwrite_checkpointrZ rechunkify) metadata_collectorrrprocess_file_chunksrrrsparserrfile_status_printerN)*ryrpatternsrrrrrrexclude_nodumprrKrrrrr processedrrr no_cache_syncrrrrrratimerrrrrrrrrrrrr) rrrrrrt0 t0_monotonicrrrcprrrrrSs^        zArchiver.do_createc Cs|rdSt|jr|j|||||dSt|jr#|j||||dSt|jre|s4|j||||dSz t|||dd} Wn t yId} Ynwt | j} | r\|j|||| |t dS|j||||dSt |jr|sv|j ||||dS|j|||||tdSt|jr|s|j||||dd S|j|||||tdSt|jr|s|j||||d d S|j|||||tdSt|jrd St|jrd St|jrd S|d |d S) zO Call the right method on the given FilesystemObjectProcessor. rD)rrrrr)rrrrTrF)rrrrrflagsc)rrrrZdev_typebNzUnknown file type: %s)rS_ISREGst_mode process_fileS_ISDIR process_dirS_ISLNKZprocess_symlinkrMrrrkS_ISFIFO process_fiforlS_ISCHR process_devS_ISBLKS_ISSOCKS_ISDOORS_ISPORTr) rrrrrrrrrZ st_targetspecialrrrrs\                zArchiver._process_anyc CstrtrdSd}zd}||r0tdt|||dd}Wdn1s*wYn3|d||js.item_filtercs|j}|||Srrrr)r rrrrJs  r)r rrrrrr build_filterBs  zArchiver.build_filterc s tdkrtdtjdrtd||j|j}|j }|j }|j } |j } |j } |j} g} | p8| s=ts?indfdd}|||| }|rotdd d d }|d tfd d||D}||_nd}|j|ddD]}|j}| rtj|tj| d|_|j s| r|j| djs| d}z |j|| dWnty}z|dt |j|WYd}~nd}~ww| r|j| djr|rt!"d#t |jz.| r|j|d|dn!t$%|j&r| '||j|| ddn |j|| | | ||dWqztt(fy-}z|dt ||WYd}~qzd}~ww|r5|)|j sxtt*| ddd}| rx|+| d}z |j|| dWntyt}z|dt |j|WYd}~nd}~ww| sE|,D] }|d|q||r|)|j-S)zExtract archive contentsasciiz_Warning: File system encoding is "ascii", extracting non-ascii filenames will not be supported.)linuxfreebsdZnetbsdZopenbsddarwinz^Hint: You likely need to fix your locale setup. E.g. install locales and use: LANG=en_US.UTF-8NcsZtr r%|s't|jr)|ddr#d|vr+|ddf|d<dSdSdSdSdSdSNZhardlink_masterTsourcechunksr)rrPrrrhardlink_masterspartial_extractrrrfs z.peek_and_store_hardlink_mastersz%5.1f%% Extracting: %s皙?rQrstepmsgidz^Calculating total archive size for the progress indicator (might take long for large archives)c3|]}|VqdSrget_sizerrrrrwrz&Archiver.do_extract..TrZpreloadr)rrr)rpiF)rZ restore_attrs)rrrZstripped_components original_pathrz%Setting directory permissions %3.0f%%zextract.permissionstotalrr#Include pattern '%s' never matched.).rgetfilesystemencodingrrplatform startswithr rrrrrrrremptyrrr_outputsum iter_itemsrrrErrarpop extract_itemrrrBrrrrrrappendrfinishrcshowget_unmatched_include_patternsr)rrrrrrr rrrrrrdirsrfilterrextracted_sizer orig_pathZdir_itemrpatternrrrrVPs               zArchiver.do_extractc Cs|j|_|jdkrt|jddn|j}t|jd}|jdk}t|||dd} |||| Wd|jS1s:wY|jS)z$Export archive contents as a tarballautoF decompresswbrDstreamZ stream_closeZinboundN)r tar_filterrqtarfilerhrg _export_tarr) rrrrrrr. tarstreamtarstream_close_streamrrr do_export_tars   zArchiver.do_export_tarcsx|j|j}|j}|j}|j| prindfdd}||}tj |dtj d} |rUt dddd d t fd d |D} | _ndfd d fdd} j|ddD]1} | j} rtj| tjd| _| | | \}}|r|rtdt| | ||qpr| |D]}d|qjS)NcsVr!|s#t|jr%|ddr'd|vr)|ddf|d<dSdSdSdSdSdSr )rPrrrrrrrs z=Archiver._export_tar..peek_and_store_hardlink_masterszw|)fileobjrformatz%5.1f%% Processing: %srrQrzCalculating sizec3rrrrrrrrrz'Archiver._export_tar..csHjjdd|jDdd}r t|jgt|fddSt|S)zY Return a file-like object that reads from the chunks of *item*. cSsg|]\}}}|qSrr)rZchunk_id_rrr szEArchiver._export_tar..item_content_stream..T)Z is_preloadedcsjt|dS)N)Zincreaser)r+rc) read_bytes)rrrrszCArchiver._export_tar..item_content_stream..)ZpipelineZ fetch_manyr rBrrc)rZchunk_iterator)rr)rritem_content_streams  z1Archiver._export_tar..item_content_streamcsd}t}|j|_|jd|_t|j|_|j|_|j |_ |j p#d|_ |j p)d|_ d|_t|j}|tjkrtj|_d|vrtj|jtjd}durW|}n |jd|f\}}|rotj|_||_||fS|dur||_||_|}d|jf|dp|<||fS||_|}||fS|tjkrtj|_||fS|tjkrtj |_|j|_||fS|tj!krtj"|_t#|j$|_%t&|j$|_'||fS|tj(krtj)|_t#|j$|_%t&|j$|_'||fS|tj*krtj+|_||fS,dt-|j|t.t/d|fS)ad Transform a Borg *item* into a tarfile.TarInfo object. Return a tuple (tarinfo, stream), where stream may be a file-like object that represents the file contents, if any, and is None otherwise. When *tarinfo* is None, the *item* cannot be represented as a TarInfo object and should be skipped. NgeAr z+%s: unsupported file type %o for tar export)0r9TarInforrmtimerS_IMODEruidgidrunamergnamelinknameS_IFMTS_IFREGREGTYPErrErrar rrLNKTYPEr rrkS_IFDIRDIRTYPES_IFLNKSYMTYPES_IFBLKBLKTYPEmajorZrdevdevmajorminordevminorS_IFCHRCHRTYPES_IFIFOFIFOTYPErrBr/r*)rrr7tarinfoZmodebitsr rNr )rrErrrritem_to_tarinfosl            z-Archiver._export_tar..item_to_tarinfoTrrr)r rrrrrr#rr9r GNU_FORMATr_r$r%r&rrrErrarrrrrBaddfiler*rr,rr)rrrr;r rrrr.tarr/rbrr0rar7r1r)rrrErrrrrr:sF   L   zArchiver._export_tarcCsdd}dd}|jr |n|}|} t||||j|jd} | jd} | jd} |jr.d} n| durF| durFt| t| k} | sE|d nd } |d | |j |j }tj | | || |j d }d d|D}|jrnt|}|D] \}}||t|qp|D]}|d|q|jS)zDiff contents of two archivescSs(ttj|dd|DddtddS)NcSsg|]\}}|qSrrrjrrrrrB]z?Archiver.do_diff..print_json_output..)rchangesT) sort_keyscls)rrrrrdiffrrrrprint_json_output\s(z+Archiver.do_diff..print_json_outputcSs$tdddd|D|dS)Nz {:<19} {} cSsg|]\}}|qSrrrfrrrrB`rhz?Archiver.do_diff..print_text_output..)rr@rarlrrrprint_text_output_s$z+Archiver.do_diff..print_text_outputrrTNzC--chunker-params are different between archives, diff will be slow.Fz--chunker-params might be different between archives, diff will be slow. If you know for certain that they are the same, pass --same-chunker-params to override this check.)can_compare_chunk_ids content_onlycss&|]\}}|js||fVqdSr)equalri)rrrmrrrr|s$z#Archiver.do_diff..r) json_linesrarchive2rmetadatarsame_chunker_paramsrdrr rrZcompare_archives_iterrssortsortedrBr,r)rrrrrrrnrpZ print_outputZarchive1rvZcp1Zcp2rrr Zdiffsrrmr1rrrdo_diffWs8       zArchiver.do_diff)rrrcCs.||j||jdd||jS)zRename an existing archiveFr)renamerrrr)rrrrrrrrrr do_renames  zArchiver.do_renamecCsfd}tot}|s|r1t|j|kr1|rtd|d}t|_|r1ttd|S)NFz5checkpoint requested: starting checkpoint creation...Tz3checkpoint requested: finished checkpoint creation!)rnZaction_triggeredrrrrrZaction_completed)rcheckpoint_funcr checkpointedZsig_int_triggeredrrrmaybe_checkpoints    zArchiver.maybe_checkpointcCsjt|j|j|jdu|jf}|jjp|j}|j|_|r%|r%| d|j S|s)|r/| ||S| ||S)z)Delete an existing repository or archivesNzFMixing archive filters and explicitly named archives is not supported.) rr+r,r1r2rrarchivesrrr_delete_archives_delete_repository)rrrZarchive_filter_specifiedZexplicit_archives_specifiedrrrrUs   zArchiver.do_deletec s4j}ttjjf\}jjsjr+tj}jjr&| djjt |}nd_ t ddj D}|s@|j Sjdkrd}td}t|dD]C\} } zj| } Wntyzt|_ td | d | d t|d YqQwd}|jr|rd nd} || t| | t|qQ|rtd|j S|rjddtd|j Std|j Stjd} t |j!|j"jdfdd}|rdnd}d}td}d}t|dD]e\} } t#rt#$rnZzj| }Wntyt|| | t|Yqw|jr(||t|| t||sQt%|| j&d}|j'| j!jd|j(|j)d}|rMdn|d}qt#r[|*dn|dkrc|j+rt,t-t.| j/jd| dt0t-td d!Wd"|j SWd"|j S1swY|j S)#zDelete archivesrTcs|]}|jVqdSrrrrrrrrz,Archiver._delete_archives..rFrrzArchive z not found (/z).zWould delete: {} ({}/{})zDeleted archive: {} ({}/{})zFinished dry-run.rz5Done. Run "borg check --repair" to clean up the mess.zAborted.r)rrrc$jdjddSNF)rr(rrr(rrrrrrrr~ z2Archiver._delete_archives..checkpoint_funcz Would delete archive: {} ({}/{})zDeleting archive: {} ({}/{})zArchive {} not found ({}/{}).rr)rforcedr~rr Deleted data:labelrrrN)1rrNr OperationDELETErrrrinsertrconsider_checkpointslist_consideringrrrr enumerater'KeyErrorr*rrrcrrr@r@rrrrrrrrnrrrrOrrrrrYrrsummaryr)rrrrrr archive_namesZdeletedZ logger_listrm archive_nameZcurrent_archiverrr~Z msg_deleteZ msg_not_founduncommitted_deletes archive_inforrrrrrs     &              ( ((zArchiver._delete_archivesc Cs|j}|j}|js|jdkrt|j}|j}g}zt |tj \}} t |j } | d| dWntyCd} | dYnw| t| d|| d||jr| d| d | dur| dkr|j jd gd D] } | t| qvn | d n| d | t| dd|}t|ddddddst|_|jS|s|td|st|ntdtd|rdnd|st|td|jStd|jS)zDelete a repositoryrzHYou requested to completely DELETE the following repository *including* z archives it contains:NzdYou requested to completely DELETE the following repository *including* all archives it may contain:zRepository ID: z Location: rFz Archives:r*r-z/This repository seems to not have any archives.zXThis repository seems to have no manifest, so we can't tell anything about its contents.z8Type 'YES' if you understand this and want to continue: rr!r"r#FZ"BORG_DELETE_I_KNOW_WHAT_I_AM_DOINGr%zRepository deleted.zWould delete repository.zWould %s security info.keeprOzCache deleted.zWould delete cache.)rkeep_security_info cache_onlyrrCrK _locationrrNrrrcrr)r.rrrr@rarWr+rrrrrr) rrrrrrKrrrrZ n_archivesrrrrrsh                    zArchiver._delete_repositorycCsvddlm}m}|dur|d||jStj|jr+t |jtj tj Btj Bs6|d|j|jS| |S)z:Mount archive or an entire repository as a FUSE filesystemr)llfuseBORG_FUSE_IMPLNz=borg mount not available: no FUSE support, BORG_FUSE_IMPL=%s.z+%s: Mountpoint must be a writable directory)Z fuse_implrrrrrErisdir mountpointaccessR_OKW_OKX_OK _do_mount)rrrrrrrdo_mountAs* zArchiver.do_mountc Csddlm}t||d9}||||||}tdz ||j|j|jWn t y2t |_ Yn wWd|j SWd|j S1sHwY|j S)Nr)FuseOperations)Zdecrypted_cachezMounting filesystem) Zfuserrrrmountroptions foreground RuntimeErrorr+r)rrrrrrZ cached_repoZ operationsrrrrPs"      zArchiver._do_mountcCs t|jS)zun-mount the FUSE filesystem)rirrrrr do_umount^s zArchiver.do_umountcCsT|jjr|jr|d|jS|||||S|jr"|d|jS|||||S)z#List archive or repository contentszKThe --json option is only valid for listing archives, not archive contents.zQThe --json-lines option is only valid for listing archive contents, not archives.)rrrrr _list_archiveru_list_repositoryr:rrrdo_listbs  zArchiver.do_listcs|jjjdurjnjrdndfdd}trKt|jd}||Wd|j S1sCwY|j S|dd|j S)Nz {path}{NL}z<{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}csXtjj|jd}t|jd}|fddD] }tj | |qdS)Nr)rucs |jSrr)r)r rrrD~s z=Archiver._list_archive.._list_inner..) rrrrr;rur&rrr format_item)rr formatterrrr@rrr rrr _list_innerysz+Archiver._list_archive.._list_innerrr) r rrr@shortr;Zformat_needs_cacherrr)rrrrrrrrrrrps      zArchiver._list_archivec Cs|jdur |j}n|jrd}nd}t|||||j|jd}g}|j|D]}|jr3|||q%t j | |q%|jrJt t|d|id|jS)Nz {archive}{NL}z{archive:<36} {time} [{id}]{NL})rrr)r)r@rr<rrrrr)Z get_item_datarrrrrar`r) rrrrrr@r output_datarrrrrs  zArchiver._list_repository)rrcCsFt|jj|j|j|jdu|jfr||||||S||||||S)z,Show archive details such as disk space usedN) rrrr+r,r1r2_info_archives_info_repository)rrrrrrrrrdo_infos"zArchiver.do_infoc Csdd}|jjr|jjf}nd|_tdd|j|D}g}t|dD]S\} } t|||| ||j|j d} | } |j rC| | n$t t| dd | d<|| d | d <ttd jdd |i| |jrln |j sxt|| rxtq%|j rtt||d |id|jS)NcSstddd|DS)Nrocss|]}t|VqdSr)rrrrrrrrzBArchiver._info_archives..format_cmdline..)rBra)cmdlinerrrformat_cmdlinesz/Archiver._info_archives..format_cmdlineTcsrrrrrrrrrz*Archiver._info_archives..r)rrrZduration)secondsZ command_lineaF Archive name: {name} Archive fingerprint: {id} Comment: {comment} Hostname: {hostname} Username: {username} Time (start): {start} Time (end): {end} Duration: {duration} Number of files: {stats[nfiles]} Command line: {command_line} Utilization of maximum supported archive size: {limits[max_archive_size]:.0%} ------------------------------------------------------------------------------ Original size Compressed size Deduplicated size This archive: {stats[original_size]:>20s} {stats[compressed_size]:>20s} {stats[deduplicated_size]:>20s} {cache} rrrr)rrrrrrrrrrrrr)r=rrtextwrapdedentstripr@rrcrar`) rrrrrrrrrrmrrrrrrrs@     zArchiver._info_archivescCst||d|jjid}|jrt||jSd}|jdvr!|d7}n|d|j7}|jdr6|d|7}||d <tt d  j d t |j|jd |tttttt||jS) NZ security_dirrz Encrypted: )rZ authenticatedZNozYes (%s)zkey filez Key file: %s encryptionz Repository ID: {id} Location: {location} {encryption} Cache: {cache.path} Security dir: {security_dir} )rKrr)r`Zsecurity_managerdirrrarr"r8rrrrr@rCrKrrrrrr)rrrrrrrrrrrrs2       zArchiver._info_repository)rrc s,tjjjjjjjjfs| d|j Sj dur'j d_ d}j jj dd|dgdd}td |jfd d |D|r\r\|d d ur\dd }ng}tfdd |D}g} i} jr{| t|j| 7} tD]} t| d} | dur| t|| | | 7} qt|Bt| t|B} tjd}t||jjd։fdd}td}t| }d }d }tt| ddd}|D]s}t rt !rnj|| vr|"j#rd}nJ|d 7}d||f}t$||j%j&d}|j'|j(d|j)|j*d}|rd n|d }n|j%r(d}ndj+| |j,d | |j,d d}j-rI|.dj+|t/|d q|0t rW| d!n|d kr_|j1rt2t3t4|j5j+d"|d#t6t3td$d%Wd|j SWd|j S1swY|j S)&z6Prune repository archives according to specified ruleszAt least one of the "keep-within", "keep-last", "keep-secondly", "keep-minutely", "keep-hourly", "keep-daily", "keep-weekly", "keep-monthly" or "keep-yearly" settings must be specified.Nr z\.checkpoint(\.\d+)?Tz(%s)?\Zr*)r.rZ match_endr-reversez(%s)\Zcsg|] }|jr|qSrrrarch) is_checkpointrrrB z%Archiver.do_prune..rrcsg|]}|vr|qSrrr) checkpointsrrrBsr)rrcrrrrrrrr~)rz*Archiver.do_prune..checkpoint_funcrzPruning archives %3.0f%%prunerz Would prune:zPruning archive (%d/%d):rq)rrzKeeping checkpoint archive:z&Keeping archive (rule: {rule} #{num}):)rulenumz{message:<40} {archive})messagerrrrrr)7rsecondlyminutelyhourlydailyweeklymonthlyyearlywithinrrr1r2rrrecompilesearchrrGrIkeysrrHrrrrrrrcr_rnrr+rrrrrOrrrr@rKrrr@r*rrYrrrr)rrrrrZ checkpoint_reZarchives_checkpointsZkeep_checkpointsrrZ kept_becauserrZ to_deleterr~Z list_loggerZ to_delete_lenZarchives_deletedrrrZ log_messagerr)rrrrrrrdo_prunes                3 33zArchiver.do_prune)tam disable_tam archives_tam)rrrrc Cs|jrtj|tjjf|jd\}}t|||}t}|jj dgdD]g}|j }t |} | |} | || } |j| dd\} } }| st| d} dd| jD| _|j| dd } || }||| ||||||jf|j|j<td | d t|d q#td | q#||jdd|Wd|j4S1swY|j4S|jr(tj|tjjf|jd\}}|jr|j ddstd|jj dgdD]}tt |qd|jd<||jdd|jst |drd|_|!|j"tdt |drtd|#t|s%t$|}t%|d&td|j4S|j'rytj|tj(dd\}}t|rCt)*t$||jrgt |drgd|_|!|j"tdt |drgtd|#d|jd<||jdd|j4St+|j,j-dd}z |j.|j/|j0|j1dWnt2y}z td|WYd}~nd}~wwt3|j,j-dd}z|j.|j/|j0|j1dW|j4St2y}ztd|WYd}~|j4Sd}~ww)z,upgrade a repository from a previous version)Zforce_tam_not_requiredr*rT)Z internal_dictcSsg|]}t|qSr)rs)rargrrrrBlrhz'Archiver.do_upgrade..sarchivecontextzAdded archive TAM: z -> []zArchive TAM present: FrNs tam_requiredzManifest contents:r6r7r8z Key location:rzUpdated security database)r)inplacerz warning: %s)5rrNrrCHECKforcerrrrrKr@rdecryptZunpack_and_verify_archiver{rZpack_and_authenticate_metadataas_dictid_hashZ add_chunkZ chunk_decrefr*rrrCrrrZ tam_verifiedconfigr%r9r6Z _passphraser8r$rrrrrEunlinkrrrupgraderrrNotImplementedErrorrr)rrrrrrrrZ archive_idZarchive_formattedcdatarorZverifiedrAZnew_archive_idrrrWrrrr do_upgrade]s        DD          zArchiver.do_upgrade)rrrc CsR||j|j}|j|_|j|_|jdk}|jdk}t|||||f|j|j|j |j |j |||j |j |j|j|j|jd } |jjrb|jj} | | rS|d| |jS| | |j|jsa|dn3|jduro|d|jS|jjdgd D]} | j} | | rqwtd | | | |jstd | qw|js| |j!d d |!|jS)zRe-create archivesneveralways) rrrrr recompressalways_recompressrrrrrrJz;Refusing to work on temporary archive of prior recreate: %sz~Nothing to do. Archive was not processed. Specify at least one pattern, PATH, --comment, re-compression or re-chunking option.Nz(--target: Need to specify single archiver*rZ Processingz=Skipped archive %s: Nothing to do. Archive was not processed.Fr)"r rrrrrrrrrrrrrrrrrJrrZis_temporary_archiverrrecreaterrJrrrrrrrr) rrrrrrr rrZ recreaterrrrrr do_recreatesL            zArchiver.do_recreatec Cs|j|_|j|_|jdkrt|jddn|j}t|jd}|jdk}t|||dd} ||||||| Wd|jS1sAwY|jS)z&Create a backup archive from a tarballr2Tr3rbrDr6N) rrr8rqr9rhrg _import_tarr) rrrrrrr.r;r<r=rrr do_import_tars   zArchiver.do_import_tarcCsLt}t}t||||jj|d|j|j|j|||j d } t ||| j | j |jdd} t ||| j| j |j|j|j |j|jd } tj|d|jd} | } | sOn~| rf| j| dtj| d }| jjd 7_n_| rt| j| d tjd }nQ| r| j| d tj d }nC| !r| j| dtjd }n5| "r| j#| dtj$d }n'| %r| j#| dtj&d }n| 'r| j(| dtj)d }n d}|*d| j+| j,||| j+qH| -|jr| jj.dd| j| j7_| j/|j0|j1d|j|j2O_|jr$|j2r t3t4| j5| j6d| iddSt7t8t9| t8t:t9| jt9| j6t8t;|jdur |d |jSz |jd \}}Wnty=|jr6d p7d }|j}Ynw|jr\ttj j f\}} t ||j t | ||j d } z|jrp| j| jj} | jj} |} n j} fdd} |} |jr| ||dd| ||t| |dkr| || n\|jr|| nT|jr| |||j|| vr| || |||j| n3z t| ||Wn(tjtjfy}zt|t j!dt"WYd}~W|jr| #SSd}~wwt$W|jr| #SS|jr| #ww)z@get, set, and delete values in a repository or cache config fileNTcSs<|dvrtd|dvr$|r"zt|WdSty!tddwdS|dvre|r_zt|Wn ty<tddw|dkrOt|tdkrMtddS|d krat|tkrctd tdSdSdS|d vrw|rs|d vrutddSdS|d vr|rzt|}Wntddt|dkrtddSdStd)NrInvalid section)segments_per_dirlast_segment_checkedz Invalid value)max_segment_sizeadditional_free_spacerrrz"Invalid value: storage_quota < 10Mrz%Invalid value: max_segment_size >= %d)r)0rM)rKz$Invalid value, must be 64 hex digits Invalid name) ValueErrorintr?MAX_SEGMENT_SIZE_LIMITrrc)sectionrvalue check_valueZbin_idrrr repo_validateUsT           z)Archiver.do_config..repo_validatecSs4|dvrtd|dvr|rt|dSdStd)Nrr)Zprevious_locationr)rr4)r!rr"r#rrrcache_validatexs z*Archiver.do_config..cache_validatecsdttttdjjd}tddD]&}|jd|dd}|dur2||}|dur2td |t|d |qd D]}|jd|dd}|durMq>t|d |q>dS) NrMr)versionrrrrrz [repository])r&rrrrrrKrFrzFThe repository config is missing the %s key which has no default valuez = )r)rZDEFAULT_SEGMENTS_PER_DIRr rrrrr-)rZdefault_valuesrr"rrr list_configs*  z'Archiver.do_config..list_configz No config key name was provided..rrrcsjjSr)Z save_configrrrrrrrDsz$Archiver.do_config..F)r#rr)NT)%rrrrrrrrNrrWRITErrrZ cache_config_configrrrO remove_optionrcrremove_sectionr"sections add_sectionrrr configparser NoOptionErrorNoSectionErrorrrr*rr))rrrr$r%r'r!rrrrrrvalidaterrrr do_configQsp  #               zArchiver.do_configcCs&tttdtjtdttS)z6display system information for debugging / bug reportszCRC implementation:z Process ID:)rrXr rr}r)rrrr do_debug_infos   zArchiver.do_debug_infoc Cst||||jj|jd}t|jjD]4\}}||||}d|t |f} t d| t | d } | |Wdn1sAwYqt dt S)zAdump (decrypted, decompressed) archive items metadata (not: data)rqz %06d_%s.itemsDumpingr5NDone.)rrrrrrwitemsrrrCrrrr)) rrrrrrrmitem_idrofilenamerprrrdo_debug_dump_archive_itemss   z$Archiver.do_debug_dump_archive_itemscsz |jtjjWntytjjwdfddfdd}tj d }||Wdt S1sDwYt S)z)dump decoded archive metadata (not: data)cstjtj|dddS)Nindentro)r1)rr=rr)rr<rr do_indentsz1Archiver.do_debug_dump_archive..do_indentcs,|d|dtjjd|d|t|ddd}tj |t d}|d|t||d|dtj d t d }d }|d D]*}||}| ||D]}t|}|r|d }n|d||qqq_|d |ddS)Nz{ z "_name": z, z "_manifest_entry": sid object_hookz "_meta": z "_items": [ F)use_listr@Tsitemsrz ] } ) rrrrrrDrrrmunpackbrQZUnpackerfeed)rproZarchive_org_dictZunpackerr+r8r)archive_meta_origrr>rrrrr$s2          z.Archiver.do_debug_dump_archive..outputrN) rZ get_raw_dictrArrrrZ DoesNotExistrhrr))rrrrrr$rpr)rDrr>r=rrrdo_debug_dump_archives    zArchiver.do_debug_dump_archivecCsh|d||j}ttj|td}t|jd}t j ||ddWdt S1s-wYt S)z dump decoded repository manifestNr?rr;r<) rrrHrDrmrBrQrhrrdumpr))rrrrrrometarprrrdo_debug_dump_manifests zArchiver.do_debug_dump_manifestc sXddlm}dfdd }|jrk|D]\}}}}} |tkr&|||nqd} |j|j|jdD]7\}}}}} |tkrH|| ||d|| d n|tkrW|| |dd || d n|tkre|| ddd || d | d7} q2n;|j ddd } | | d}|||d} d} |j t | d } | sn| d} | D]}| |}|| ||| d7} qqt dtS)zOdump (decrypted, decompressed) repo objects, repo index MUST be current/correctr key_factoryNcs|dur|tjkr |nd}||}nd}|durdnd|}|dur*dt|nd} |dur6dt|nd} |durBdt|nd} d|| | || f} td| t| d} | |WddS1shwYdS)NrFrAz%08d%s%s%s%s.objr5r5)rNrHrrrCrrr)rmrKrtagsegmentoffsetgive_idrotag_strZ segment_strZ offset_strZid_strr9rprrr decrypt_dump(s   "z6Archiver.do_debug_dump_repo_objs..decrypt_dumpr)rMrNr )rLrMrNdelrlimitmarkerTrr6)NNN) crypto.keyrJghostZscan_low_levelrrMrNrrrrscanrrr))rrrrJrRrKrrLrMrNrmidsrVresultrrQrdo_debug_dump_repo_objs#sF          z Archiver.do_debug_dump_repo_objsc sdfdd}|j}z"|drt|dd}n|dr(|dd}ntdWn ttfy:d}Ynw|sD|d tSd d lm }|j d dd }| |d }|||}d} d} d} d } |j t | d } | spn| d} | D]}| |}|tjkr|nd}|||}| t|d  d|dt|d }||vr| t|d  d|dt|d }||}d| | |f}|||||||}|r||}d| ||f}|||||||} } | d 7} | dd krtd| qvqftdtS)zMsearch for byte sequences in repo objects, repo index MUST be current/correctrc sZ|||}||t||t|}td|||||||dS)Nz{}: {} {} {} == {!r} {!r} {!r})rcrr@hex)rwantedrorNbeforeafterrrr print_finding`s   z9Archiver.do_debug_search_repo_objs..print_findingzhex:r;Nzstr:zunsupported search termz6search term needs to be hex:123abc or str:foobar stylerrIrTrrKTrz %d %s | %sz %d %s #%drvz%d objects processed.r6)r^r"rencoderUnicodeEncodeErrorrr+rWrJrrrYrrNrHrrcfindr]rjrr))rrrrar^rJrZrrrVZ last_dataZlast_idrmr[rKrOroZ boundary_datarNrrjrrrdo_debug_search_repo_objs[sh        *2     z"Archiver.do_debug_search_repo_objsc Cs|j}zt|}t|dkrtdWnty1}ztd|t|ftWYd}~Sd}~wwz||}Wntj yKtd|tYSwt |j d }| |Wdn1sbwYtd|t S)z>get object contents from the repository and write it into filer#id must be 256bits or 64 hex digitsobject id %s is invalid [%s].Nobject %s not found.r5zobject %s fetched.)rKrrcrrrr+rrObjectNotFoundrrrr))rrrhex_idrKerrrorrrrdo_debug_get_objs,    zArchiver.do_debug_get_objcCsNt|jd }|}Wdn1swY||}t|tS)z!compute id-hash for file contentsrN)rrreadrrr]r))rrrrrrrorKrrrdo_debug_id_hashs    zArchiver.do_debug_id_hashc Cst|jd }|}Wdn1swY|j}zt|}t|dkr,tdWntyK}ztd|t|ft WYd}~Sd}~ww| ||td||j ddt S) z%put file contents into the repositoryrNrrfrgzobject %s put.Fr) rrrmrKrrcrrrr+r rr))rrrrrorjrKrkrrrdo_debug_put_objs$     zArchiver.do_debug_put_objc Csd}|jD]7}zt|}Wntytd|Yqwz||d}td|Wqtjy<td|Yqw|rE|jddtdtS)z3delete the objects with the given IDs from the repoFobject id %s is invalid.Tzobject %s deleted.rhrr6) rZrrrrOrrirr))rrrmodifiedrjrKrrrdo_debug_delete_objs$     zArchiver.do_debug_delete_obj)rrrrc Cs||jD]8}zt|}Wntytd|Yqwz|j|d}td||fWqty;td|YqwtS)z4display refcounts for the objects with the given IDsrprz4object %s has %d referrers [info from chunks cache].z-object %s not found [info from chunks cache].)rZrrrr rr)) rrrrrrrjrKZrefcountrrrdo_debug_refcount_objs    zArchiver.do_debug_refcount_objcCs|js ||z?t|j|j|jdd|jDd}t |j d}t j ||ddWdn1s7wYW| tSW| tS| w)zdump repository hintscSsi|] \}}t||qSr)rdecode)rkvrrr sz0Archiver.do_debug_dump_hints..)segmentsrstorage_quota_use shadow_indexrr;r<N)Z _active_txnZ prepare_txnZget_transaction_iddictrxrryrzr7rhrrrFZrollbackr))rrrhintsrprrrdo_debug_dump_hintss$ zArchiver.do_debug_dump_hintsc Csddl}|j2|j|tj|jddd|jWdn1s$wYWdtSWdtS1s`_, selector `fm:` This is the default style for ``--exclude`` and ``--exclude-from``. These patterns use a variant of shell pattern syntax, with '\*' matching any number of characters, '?' matching any single character, '[...]' matching any single character specified, including ranges, and '[!...]' matching any character not specified. For the purpose of these patterns, the path separator (backslash for Windows and '/' on other systems) is not treated specially. Wrap meta-characters in brackets for a literal match (i.e. `[?]` to match the literal character `?`). For a path to match a pattern, the full path must match, or it must match from the start of the full path to just before a path separator. Except for the root path, paths will never end in the path separator when matching is attempted. Thus, if a given pattern ends in a path separator, a '\*' is appended before matching is attempted. A leading path separator is always removed. Shell-style patterns, selector `sh:` This is the default style for ``--pattern`` and ``--patterns-from``. Like fnmatch patterns these are similar to shell patterns. The difference is that the pattern may include `**/` for matching zero or more directory levels, `*` for matching zero or more arbitrary characters with the exception of any path separator. A leading path separator is always removed. Regular expressions, selector `re:` Regular expressions similar to those found in Perl are supported. Unlike shell patterns regular expressions are not required to match the full path and any substring match is sufficient. It is strongly recommended to anchor patterns to the start ('^'), to the end ('$') or both. Path separators (backslash for Windows and '/' on other systems) in paths are always normalized to a forward slash ('/') before applying a pattern. The regular expression syntax is described in the `Python documentation for the re module `_. Path prefix, selector `pp:` This pattern style is useful to match whole sub-directories. The pattern `pp:root/somedir` matches `root/somedir` and everything therein. A leading path separator is always removed. Path full-match, selector `pf:` This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or unspecified parts - the full path must be given. `pf:root/file.ext` matches `root/file.ext` only. A leading path separator is always removed. Implementation note: this is implemented via very time-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns without impacting performance much). Due to that, this kind of pattern does not respect any context or order. If you use such a pattern to include a file, it will always be included (if the directory recursion encounters it). Other include/exclude patterns that would normally match will be ignored. Same logic applies for exclude. .. note:: `re:`, `sh:` and `fm:` patterns are all implemented on top of the Python SRE engine. It is very easy to formulate patterns for each of these types which requires an inordinate amount of time to match paths. If untrusted users are able to supply patterns, ensure they cannot supply `re:` patterns. Further, ensure that `sh:` and `fm:` patterns only contain a handful of wildcards at most. Exclusions can be passed via the command line option ``--exclude``. When used from within a shell, the patterns should be quoted to protect them from expansion. The ``--exclude-from`` option permits loading exclusion patterns from a text file with one pattern per line. Lines empty or starting with the number sign ('#') after removing whitespace on both ends are ignored. The optional style selector prefix is also supported for patterns loaded from a file. Due to whitespace removal, paths with whitespace at the beginning or end can only be excluded using regular expressions. To test your exclusion patterns without performing an actual backup you can run ``borg create --list --dry-run ...``. Examples:: # Exclude '/home/user/file.o' but not '/home/user/file.odt': $ borg create -e '*.o' backup / # Exclude '/home/user/junk' and '/home/user/subdir/junk' but # not '/home/user/importantjunk' or '/etc/junk': $ borg create -e 'home/*/junk' backup / # Exclude the contents of '/home/user/cache' but not the directory itself: $ borg create -e home/user/cache/ backup / # The file '/home/user/cache/important' is *not* backed up: $ borg create -e home/user/cache/ backup / /home/user/cache/important # The contents of directories in '/home' are not backed up when their name # ends in '.tmp' $ borg create --exclude 're:^home/[^/]+\.tmp/' backup / # Load exclusions from file $ cat >exclude.txt <`_, e.g. {now:%Y-%m-%d_%H:%M:%S} {utcnow} The current UTC date and time, by default in ISO-8601 format. You can also supply your own `format string `_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S} {user} The user name (or UID, if no name is available) of the user running borg. {pid} The current process ID. {borgversion} The version of borg, e.g.: 1.0.8rc1 {borgmajor} The version of borg, only the major version, e.g.: 1 {borgminor} The version of borg, only major and minor version, e.g.: 1.0 {borgpatch} The version of borg, only major, minor and patch version, e.g.: 1.0.8 If literal curly braces need to be used, double them for escaping:: borg create /path/to/repo::{{literal_text}} Examples:: borg create /path/to/repo::{hostname}-{user}-{utcnow} ... borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ... borg prune --glob-archives '{hostname}-*' ... .. note:: systemd uses a difficult, non-standard syntax for command lines in unit files (refer to the `systemd.unit(5)` manual page). When invoking borg from unit files, pay particular attention to escaping, especially when using the now/utcnow placeholders, since systemd performs its own %-based variable replacement even in quoted text. To avoid interference from systemd, double all percent signs (``{hostname}-{now:%Y-%m-%d_%H:%M:%S}`` becomes ``{hostname}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}``). placeholdersa It is no problem to mix different compression methods in one repo, deduplication is done on the source data chunks (not on the compressed or encrypted data). If some specific chunk was once compressed and stored into the repo, creating another backup that also uses this chunk will not change the stored chunk. So if you use different compression specs for the backups, whichever stores a chunk first determines its compression. See also borg recreate. Compression is lz4 by default. If you want something else, you have to specify what you want. Valid compression specifiers are: none Do not compress. lz4 Use lz4 compression. Very high speed, very low compression. (default) zstd[,L] Use zstd ("zstandard") compression, a modern wide-range algorithm. If you do not explicitly give the compression level L (ranging from 1 to 22), it will use level 3. Archives compressed with zstd are not compatible with borg < 1.1.4. zlib[,L] Use zlib ("gz") compression. Medium speed, medium compression. If you do not explicitly give the compression level L (ranging from 0 to 9), it will use level 6. Giving level 0 (means "no compression", but still has zlib protocol overhead) is usually pointless, you better use "none" compression. lzma[,L] Use lzma ("xz") compression. Low speed, high compression. If you do not explicitly give the compression level L (ranging from 0 to 9), it will use level 6. Giving levels above 6 is pointless and counterproductive because it does not compress better due to the buffer size used by borg - but it wastes lots of CPU cycles and RAM. auto,C[,L] Use a built-in heuristic to decide per chunk whether to compress or not. The heuristic tries with lz4 whether the data is compressible. For incompressible data, it will not use compression (uses "none"). For compressible data, it uses the given C[,L] compression - with C[,L] being any valid compression specifier. obfuscate,SPEC,C[,L] Use compressed-size obfuscation to make fingerprinting attacks based on the observable stored chunk size more difficult. Note: - You must combine this with encryption, or it won't make any sense. - Your repo size will be bigger, of course. - A chunk is limited by the constant ``MAX_DATA_SIZE`` (cur. ~20MiB). The SPEC value determines how the size obfuscation works: *Relative random reciprocal size variation* (multiplicative) Size will increase by a factor, relative to the compressed data size. Smaller factors are used often, larger factors rarely. Available factors:: 1: 0.01 .. 100 2: 0.1 .. 1,000 3: 1 .. 10,000 4: 10 .. 100,000 5: 100 .. 1,000,000 6: 1,000 .. 10,000,000 Example probabilities for SPEC ``1``:: 90 % 0.01 .. 0.1 9 % 0.1 .. 1 0.9 % 1 .. 10 0.09% 10 .. 100 *Randomly sized padding up to the given size* (additive) :: 110: 1kiB (2 ^ (SPEC - 100)) ... 120: 1MiB ... 123: 8MiB (max.) Examples:: borg create --compression lz4 REPO::ARCHIVE data borg create --compression zstd REPO::ARCHIVE data borg create --compression zstd,10 REPO::ARCHIVE data borg create --compression zlib REPO::ARCHIVE data borg create --compression zlib,1 REPO::ARCHIVE data borg create --compression auto,lzma,6 REPO::ARCHIVE data borg create --compression auto,lzma ... borg create --compression obfuscate,110,none ... borg create --compression obfuscate,3,auto,zstd,10 ... borg create --compression obfuscate,2,zstd,6 ... rcCs|js ||j S|j|jvrtt|j|j|j S|j|vrM|jr0t||jj|j S|jrCd||j_||j|j S||j|j Sg}|d|jg7}|dg7}|ddt | g7}|ddt |j g7}| d||j S)NzNo help available on %s.zTry one of the following:z Commands: %s, z Topics: %sr) topic print_helphelptextrrt epilog_onlyepilog usage_onlyrarzrrr)rrcommandsr msg_linesrrrdo_help s.      zArchiver.do_helpcCs |tS)zdisplay infos about subcommand)rr))rrrrrrdo_subcommand_help szArchiver.do_subcommand_helpcCsfgd}t|ddD]$\}}|D]\}}}||r/|dur(|||||<t|tjdqq |S)N)) --noatimeNzGWarning: "--noatime" has been deprecated because it is the default now.) --nobsdflagsNzCWarning: "--nobsdflags" has been deprecated. Use --noflags instead.)--numeric-ownerNzJWarning: "--numeric-owner" has been deprecated. Use --numeric-ids instead.)--remote-ratelimitNzRWarning: "--remote-ratelimit" has been deprecated. Use --upload-ratelimit instead.)--remote-bufferNzLWarning: "--remote-buffer" has been deprecated. Use --upload-buffer instead.)--prefixNzZWarning: "--prefix" has been deprecated. Use "--glob-archives 'yourprefix*'" (-a) instead.r)rr"replacerrr)rrZ deprecationsrmrZold_namenew_namerrrrpreprocess_args s  zArchiver.preprocess_argsc@s2eZdZdZddZd ddZdejfdd Zd S) zArchiver.CommonOptionsa Support class to allow specifying common options directly after the top-level command. Normally options can only be specified on the parser defining them, which means that generally speaking *all* options go after all sub-commands. This is annoying for common options in scripts, e.g. --remote-path or logging options. This class allows adding the same set of options to both the top-level parser and the final sub-command parsers (but not intermediary sub-commands, at least for now). It does so by giving every option's target name ("dest") a suffix indicating its level -- no two options in the parser hierarchy can have the same target -- then, after parsing the command line, multiple definitions are resolved. Defaults are handled by only setting them on the top-level parser and setting a sentinel object in all sub-parsers, which then allows one to discern which parser supplied the option. cCs(||_||_t|_t|_t|_dS)a *define_common_options* should be a callable taking one argument, which will be a argparse.Parser.add_argument-like function. *define_common_options* will be called multiple times, and should call the passed function to define common options exactly the same way each time. *suffix_precedence* should be a tuple of the suffixes that will be used. It is ordered from lowest precedence to highest precedence: An option specified on the parser belonging to index 0 is overridden if the same option is specified on any parser with a higher index. N)define_common_optionssuffix_precedencer{common_optionsrappend_optionsobjectdefault_sentinel)rrrrrrr s   zArchiver.CommonOptions.__init__Fcs8jvsJfdd}|d|dS)a Add common options to *parser*. *provide_defaults* must only be True exactly once in a parser hierarchy, at the top level, and False on all lower levels. The default is chosen accordingly. *suffix* indicates the suffix to use internally. It also indicates which precedence the *parser* has for common options. See *suffix_precedence* of __init__. csd|vrS|dd|ddvsJ|ddk}|r-j|d|dgks,Jdn jt|d|d7<sS|d||d<|sSj|d<j|i|dS) Nractionstore)help store_const store_true store_falserr)r)rzCThe default is explicitly constructed as an empty list in resolve()r) setdefaultrrrrr add_argument)rrZ is_appendZ common_groupprovide_defaultsrsuffixrrr s   z=Archiver.CommonOptions.add_common_group..add_argumentzCommon optionsN)radd_argument_groupr)rrrrrrrradd_common_group s  z'Archiver.CommonOptions.add_common_grouprc Cs|jD]4}|j|gD]*}||}|}t|||j}||jur&t|||zt||Wq ty6Yq wq|jD]'}g}|jD]}||}||vr[t||} t||| | qBt|||q;dS)zd Resolve the multiple definitions of each common option to the final value. N) rrrrrrdelattrAttributeErrorrextend) rrrrZmap_fromZmap_tor"Z option_valueZ extend_fromrrrrresolve0 s0         zArchiver.CommonOptions.resolveN)F) rrrrrrrZ Namespacerrrrr CommonOptions s  (rc9 sBddddddddfd d }d d }d d dddfdddddddfdd}tjjdd d}|jtj|ggdj|dd|_|j ddd d!t d"d#|jj |d$dd%tjd jd&}|jggd'|j |d(tjd jd&}|jggd'|j |d)|d*}|jd+krj j |_||_tj|_d,|_|||S|jd-d.d/}|d0} |jd1|gd d2| tjd2d3} | jd-d.d/} | jtj| d4|d5} | jd6|gd jj | tjd7d3} | jjd8| j d9d:td d;dd?d@dA|dB} |jdC|gd jj | tjdDd3} | jjd8| j d9d:dEdFtd d;dGdH|dI}|jdJ|gd jj |tjdKd3} | jjd8| j d9dLdEdFtdMdH| j dNdOdPdQdR| j dSdTdPdUdR| j dVdWdPdXdR| j dYdZdPd[dR| j d\d]dPd^dR| j d_d`datdbdcdd| |de}|jdf|gd jj |tjdgd3} | jjd8| j d9d:dEdFtd d;dhdH| j didjdPdkdR| j dldmdntdodpdd|dq}|jdr|gd jj |tjdsd3} | jjd8| j dtdudvdPdwdR| }|j dxdydzdPd{dR|j d|d}d~dPddR| j d9d:dEdFtd ddddH| j dddEdd| j dddEdd|d}|jd|gd jj |tjdd3} | jjd8| j ddddPddR| j ddddPddR| j d}ddPddR| j dddtdd| j ddPdd| j dddPddR| j dddddd| j dddt dbdd| j dddt!dbdd| j dddddt"ddd| j ddPdd| j ddPdd| j ddPdd| j ddddA| dd}|j dddPddR| #d¡}|j ddddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddPddR|j dddtt$t%dt%d|j dddPddR| #d}|j dddt&dFdd|j dddt'dddd|j dtdd`dtdddd|j dddt(t)tdt)d|j ddddt*t*dddd| j d9dtdd;d d=| j d d?d t+d d d|d}|jd|gd d|tjdd3} | jd-d.d/}| jtj| d4|d}|jd|gd j,j |tjdd3} | jj,d8|d}|jd|gd j-j |tjdd3} | jj-d8| j d9dtdd;dd=|d}|jd|gd j.j |tjdd3} | jj.d8| j d9dtdd;dd=| j d>d?t+dd=|d}|jd|gd j/j |tjdd3} | jj/d8| j d9d:td d;d d=| j d>d?t+dd=|d!}|jd"|gd j0j |tjd#d3} | jj0d8| j d9d:td d;d d=| j d$d%dPd&dR| j d'd(d)dt1d*d+| j d,d-d.dt1d/d+|d0}|jd1|gd j2j |tjd2d3} | jj2d8| j d9d:td d;d3d=| j d4d5t+d6d=|d7}|jd8|gd j3j |tjd9d3} | jj3d8| j d9d:td d;d:d=| j d>d?t+d;d=|d<}|jd=|gd j4j |tjd>d3} | jj4d8| j d9d:td d;d:d=| j d?d@t+dAd=| j d>d?t+dBd=|dC} |jdD|gd j5j | tjdEd3} | jj5d8| j d9d:td d;d:d=| j d?d@t+dFd=| j d>d?t+dGd=|dH}!|jdI|gd j6j |!tjdJd3} | jj6d8| j d9d:td d;d:d=| j dKdLdMt+dNdO|dP}"|jdQ|gd j7j |"tjdRd3} | jj7d8| j d9d:td d;d:d=| j dKdLdMt+dSdO|dT}#|jdU|gd j8j |#tjdVd3} | jj8d8| j d9d:td d;d d=| j d>d?t+dd=|dW}$|jdX|gd j9j |$tjdYd3} | jj9d8| j dZd[t:d\d]d=| j d^d_t:d`dad=|db}%|jdz|gd j;j |%tjdcd3} | jj;d8| j ddddPdddR| j d}ddPdedR| j ddddPdfdR| j dgdhdPdidR| j djdkdldbdmdn| j dodpdPdqdR| j d\d]dPd^dR| j dtdd`dtdddd| j d9dLdEdFtdrdH| j dsdd dtd| |du}&|jdv|gd jj |'tjdd3} | jj>d8| j ddddd| j d}ddPddR| j d9dtdd;dd=| j ddddA| j d d?d t+ddO| dd|d}(|jd|gd j?j |(tjdd3} | jj?d8| j d}ddPddR| j ddddPddR| j dddPddR| j dddPddR| j dddPddR| j dddPddR| j dddPddR| j dddPddR| j dddPddR| j dddPddR| j d9dtdd;dd=| j d d?d t+ddO| dd|jd|gd dd} | j dddPd| j dddPd| jtj@||jAd8| j ddt+dEdd|d})|jd|gd jBj |)tjdd3} | jjBd8| j d9dLdEdFtddH| j ddPdd| |d}*|jd|gd jCj |*tjdd3} | jjCd8| j d9d:dEdFtd d;ddH| j dddddtDdd| j dddPddR| j ddddtEdÐd+| j dĐddPddR|jd|gd ddFtjdd3} | jd-d.d/}+| jtj| d4|dʃ},|+jd|gd jFj |,tjdd3} | jjFd8| j d9d:dEdFtd d;d͍| j d>d?dEt+dΐdO| j dϐddPddR| j dҐddPddR|dՃ}-|+jd|gd jGj |-tjdd3} | jjGd8| j d9d:dEdFtd d;d͍| j d>d?dEt+dؐdO| j dϐddPddR|dڃ}.|+jd|gd jHj |.tjdd3} | jjHd8| j d9d:dEdFtd d;d͍|d݃}/|+jd|gd jIj |/tjdd3} | jjId8| j d9d:dEdFtd d;d͍|dtJKtLMdtNKtLMdtOK}0|jd~|gd jPj |0tjdd3} | jjPd8| j ddPddd| j dddPddR| j ddddd| j ddPdd| j ddPdd| j d9dLdEdFtddH| j d d?d t+ddO| | |jd|gd j j |tjd,d3} || |d}1|jd|gd jQj |1tjdd3} | jjQd8| j ddddPdddR| j djdkdPddR| j ddddPdfdR| j d}ddPddR| j dddtRdd| j dddtdbdd| j ddtdbdd| j ddd tdbd d| j dxd d tdbd d| j dddtdbdd| j dddtdbdd| j dddtdbdd| d d d| j d\d]dPd^dR| j dtdd`dtdddd| j d9d:dEdFtd d;ddH|d}2|jd|gd jSj |2tjjSj d3} | jjSd8| j d}ddPddR| j dddtdd| j ddddPddR| j ddddPddR| dd| #d}|j d d!d"dt=d#d$|j dtddtdd`dd%|j dddt&ddd|j dddt'dd&dd|j ddddt*t*dddd|j d'dd(dEd)d*d+d,d-|j dddtt(dd.d| j d9dLdEdFtd/dH| j d d?d t+d0dO|d1}3|jd2|gd jTj |3tjd3d3} | jjTd8| j d9dtdd;d4d=| j dd5t=d6d=|d7}4|jd8|gd jUj |4tjd9d3} | jjUd8| j d:d?d;d<d=d| j d>d?d?d<d@d| j dddPdAdR| j dddtEddBdd|dC}5|jdD|gd jVj |5tjdEd3} | jjVd8| j dFdGt+dHd=|dI}6|jdJ|gd jWj |6tjdKd3} | jjWd8| j ddddPdddR| j dLdMdPdNdR| j djdOdPdPdR| j dQdRdPdSdR| j dTdUdPdVdR| j dWdXdPdYdR| j d9d:dEdFtd d;dZdH|d[}7|jd\|gd jXj |7tjd]d3} | jjXd8| j d9d:td d;d^d=| j d_d`dadA| j dbdctjYddd|de}8|jdf|gd jZj |8tjjZj d3} | jjZd8| j dddtddg| j ddddPd ddn| j d}ddPd ddn| j dddtdhdi| j ddPdjd| j dkdldPd dmdn| #d}|j ddddFddn|j ddt'ddd&d%|j dtddtdd`dd%|j ddtt(t)ddt)do|j ddddt*t*dddd| j d9dtdd;d d=| j ddpdqdA|S(rNu;"I am seeing ‘A’ (added) status for a unchanged file!?"z"Separate compaction"z "Item flags"z"borg help patterns"z"borg help placeholders"z:Internals -> Data structures and file formats -> Key fileszborg key export --help)Za_status_oddityZseparate_compactionZlist_item_flagsZ borg_patternsZborg_placeholdersZ key_filesZborg_key_exportcsft|}ztj}Wn tyd}Ynw|dvr#dd|D}d|}|dkr1t|}|S)N command-line)r build_usagecSsg|] }|ds|qS)z.. man)r")rlinerrrrBn rzAArchiver.build_parser..process_epilog..r)rr splitlinesborgdoc_moderrart)rr)rst_plain_text_referencesrrprocess_epilogg s    z-Archiver.build_parser..process_epilogc Ss|ddddd|dddd d d d |d dddd dd |dddd d dd |ddddddd dd |ddddd dd |ddddgdd|d d!d"d#d$d%|d&d'd#d(d%|d)d*d#d+d%|d,d-d.td/d0d1|d2d3d4tjd5d6|d7d8d#d9d%|d:d;d#dd?d@dAtdBd1|dCdDdEdFdG|dHdIdJtdKdL|dMdIdJtdNdL|dOdPdQtdRdL|dSdPdQtdTdL|dUdVd#dWd%|dXdYdZdd[d\|d]d^d_d`dGdS)aN-hz--helprzshow this help message and exitrrz --critical log_levelrcriticalrzwork on log level CRITICAL)rrconstrrz--errorrzwork on log level ERRORz --warningz#work on log level WARNING (default)z--infoz-vz --verboserzwork on log level INFOz--debugrz,enable debug output, work on log level DEBUGz --debug-topicTOPIC debug_topicsr)zenable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified.)metavarrrrrz-pz --progressrrzshow progress informationrrrz--iecrz%format using IEC units (1KiB = 1024B)z --log-jsonrz>Output one JSON object per log line instead of formatted text.z --lock-waitSECONDSrrzRwait at most SECONDS for acquiring a repository/cache lock (default: %(default)d).rrrrrz --bypass-lockrrzBypass locking mechanismrrrrz--show-version show_versionzshow/log the borg versionz --show-rcshow_rczshow/log the return code (rc)z--umaskMumaskcS t|dSNrrrrrrD  zFArchiver.build_parser..define_common_options..z3set umask to M (local only, default: %(default)04o)z --remote-pathPATHZ remote_pathz;use PATH as borg executable on the remote (default: "borg")rrrrZRATEZupload_ratelimitz.deprecated, use ``--upload-ratelimit`` insteadrrrrz--upload-ratelimitz@set network upload rate limit in kiByte/s (default: 0=unlimited)rZ UPLOAD_BUFFERZ upload_bufferz+deprecated, use ``--upload-buffer`` insteadz--upload-bufferz=set network upload buffer size in MiB. (default: 0=no buffer)z--consider-part-filesrz>treat part files like normal files (e.g. to list/extract them)z--debug-profileFILE debug_profilezWrite execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".rrrrz--rshZRSHZrshzHUse this command to connect to the 'borg serve' process (default: 'ssh'))rrZSUPPRESSZ UMASK_DEFAULT)Zadd_common_optionrrrrt s          z4Archiver.build_parser..define_common_optionsF) tag_filesrc Ss|ddddtddd|dd td d |d dtd d |ddtdd |r?|ddddd|ddddtdd|ddddd|rM|ddd td!d"d#dSdS)$N-ez --excludeZPATTERNrr)zexclude paths matching PATTERNrrrrrz--exclude-fromZ EXCLUDEFILEz4read exclude patterns from EXCLUDEFILE, one per line)rrrz --patternz&include/exclude paths matching PATTERNz--patterns-fromZ PATTERNFILEz.define_exclude_and_patternscs |d}|jfi||S)NzInclude/Exclude options)rr) subparserr exclude_group)rrrdefine_exclusion_group s z5Archiver.build_parser..define_exclusion_groupT)r- first_lastc Ss|dd}|}|jddddttdd|jd d d d ttd d|r8d}|jdddt|ddt |d|rV|}|jddddt dd|jddddt dddSdS)NzArchive filtersz5Archive filters can be applied to repository targets.z-PrPREFIXr1zConly consider archive names starting with this prefix. (deprecated)rz-az--glob-archivesZGLOBr2zonly consider archive names matching the glob. sh: rules apply (without actually using the sh: prefix), see "borg help patterns".rJz --sort-byZKEYSr-zHComma-separated list of sorting keys; valid keys are: {}; default is: {}rrz--firstNr+rz:consider first N archives after other filters were appliedrrrrrz--lastr,z9consider last N archives after other filters were applied) radd_mutually_exclusive_grouprr5rr6r8r@rarOr0)rr-rZ filters_grouprZsort_by_defaultrrrdefine_archive_filters_group s6   z;Archiver.build_parser..define_archive_filters_groupcs|jjd|jddtdd|jdddd d |jd d td d|jdddddd|jddttdd|jddddd|jddddd||jdddtdd |d!d"dS)#NrrREPOSITORY_OR_ARCHIVEzrepository or archive to mountrrr--consider-checkpointsrrKShow checkpoint archives in the repository contents list (default: hidden).rrrr MOUNTPOINTzwhere to mount filesystemz-fz --foregroundrz$stay in foreground, do not daemonizerz-orzExtra mount options)rrrrrr)deprecated, use ``--numeric-ids`` instead --numeric-idsz6use numeric user and group identifiers from archive(s)rrr (paths to extract; patterns are supportedrnargsrrTr) set_defaultsrrr1rr)r)rrrrrdefine_borg_mount s8        z0Archiver.build_parser..define_borg_mountzBorg - Deduplicated Backups)r descriptionadd_help)rrr) _maincommand _midcommand _subcommand)rz-Vz --versionr&z %(prog)s zshow version number and exit)rr&rr)r)rr)rrrra This command mounts an archive as a FUSE filesystem. This can be useful for browsing an archive or restoring individual files. Unless the ``--foreground`` option is given the command will run in the background until the filesystem is ``umounted``. The command ``borgfs`` provides a wrapper for ``borg mount``. This can also be used in fstab entries: ``/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0`` To allow a regular user to use fstab entries, add the ``user`` option: ``/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0`` For FUSE configuration and mount options, see the mount.fuse(8) manual page. Borg's default behavior is to use the archived user and group names of each file and map them to the system's respective user and group ids. Alternatively, using ``numeric-ids`` will instead use the archived user and group ids without any mapping. The ``uid`` and ``gid`` mount options (implemented by Borg) can be used to override the user and group ids of all files (i.e., ``borg mount -o uid=1000,gid=1000``). The man page references ``user_id`` and ``group_id`` mount options (implemented by fuse) which specify the user and group id of the mount owner (aka, the user who does the mounting). It is set automatically by libfuse (or the filesystem if libfuse is not used). However, you should not specify these manually. Unlike the ``uid`` and ``gid`` mount options which affect all files, ``user_id`` and ``group_id`` affect the user and group id of the mounted (base) directory. Additional mount options supported by borg: - ``versions``: when used with a repository mount, this gives a merged, versioned view of the files in the archives. EXPERIMENTAL, layout may change in future. - ``allow_damaged_files``: by default damaged files (where missing chunks were replaced with runs of zeros by ``borg check --repair``) are not readable and return EIO (I/O error). Set this option to read such files. - ``ignore_permissions``: for security reasons the ``default_permissions`` mount option is internally enforced by borg. ``ignore_permissions`` can be given to not enforce ``default_permissions``. The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users to tweak the performance. It sets the number of cached data chunks; additional memory usage can be up to ~8 MiB times this number. The default is the number of CPU cores. When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process to unintentionally delete data. When running in the foreground ^C/SIGINT unmounts cleanly, but other signals or crashes do not. borgfszmount repositoryzrequired argumentsz )titlerz%These commands do various benchmarks. benchmarkzbenchmark command)parentsrrrformatter_classr)raV This command benchmarks borg CRUD (create, read, update, delete) operations. It creates input data below the given PATH and backups this data into the given REPO. The REPO must already exist (it could be a fresh empty repo or an existing repo, the command will create / read / update / delete some archives named borg-benchmark-crud\* there. Make sure you have free space there, you'll need about 1GB each (+ overhead). If your repository is encrypted and borg needs a passphrase to unlock the key, use:: BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH Measurements are done with different input file sizes and counts. The file contents are very artificial (either all zero or all random), thus the measurement results do not necessarily reflect performance with real data. Also, due to the kind of content used, no compression is used in these benchmarks. C- == borg create (1st archive creation, no compression, do not use files cache) C-Z- == all-zero files. full dedup, this is primarily measuring reader/chunker/hasher. C-R- == random files. no dedup, measuring throughput through all processing stages. R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk) R-Z- == all zero files. Measuring heavily duplicated files. R-R- == random files. No duplication here, measuring throughput through all processing stages, except writing to disk. U- == borg create (2nd archive creation of unchanged input files, measure files cache speed) The throughput value is kind of virtual here, it does not actually read the file. U-Z- == needs to check the 2 all-zero chunks' existence in the repo. U-R- == needs to check existence of a lot of different chunks in the repo. D- == borg delete archive (delete last remaining archive, measure deletion + compaction) D-Z- == few chunks to delete / few segments to compact/remove. D-R- == many chunks to delete / many segments to compact/remove. Please note that there might be quite some variance in these measurements. Try multiple measurements and having a otherwise idle machine (and network, if you use it). Zcrudz7benchmarks borg CRUD (create, extract, update, delete).rrZ REPOSITORY)rz,repository to use for benchmark (must exist)rrrz(path were to create benchmark input data)rrz This command breaks the repository and cache locks. Please use carefully and only while no borg process (on any machine) is trying to access the Cache or the Repository. z break-lockz break repository and cache locks?rFz'repository for which to break the locks)rrrrra The check command verifies the consistency of a repository and its archives. It consists of two major steps: 1. Checking the consistency of the repository itself. This includes checking the segment magic headers, and both the metadata and data of all objects in the segments. The read data is checked by size and CRC. Bit rot and other types of accidental damage can be detected this way. Running the repository check can be split into multiple partial checks using ``--max-duration``. When checking a remote repository, please note that the checks run on the server and do not cause significant network traffic. 2. Checking consistency and correctness of the archive metadata and optionally archive data (requires ``--verify-data``). This includes ensuring that the repository manifest exists, the archive metadata chunk is present, and that all chunks referencing files (items) in the archive exist. This requires reading archive and file metadata, but not data. To cryptographically verify the file (content) data integrity pass ``--verify-data``, but keep in mind that this requires reading all data and is hence very time consuming. When checking archives of a remote repository, archive checks run on the client machine because they require decrypting data and therefore the encryption key. Both steps can also be run independently. Pass ``--repository-only`` to run the repository checks only, or pass ``--archives-only`` to run the archive checks only. The ``--max-duration`` option can be used to split a long-running repository check into multiple partial checks. After the given number of seconds the check is interrupted. The next partial check will continue where the previous one stopped, until the full repository has been checked. Assuming a complete check would take 7 hours, then running a daily check with ``--max-duration=3600`` (1 hour) would result in one full repository check per week. Doing a full repository check aborts any previous partial check; the next partial check will restart from the beginning. With partial repository checks you can run neither archive checks, nor enable repair mode. Consequently, if you want to use ``--max-duration`` you must also pass ``--repository-only``, and must not pass ``--archives-only``, nor ``--repair``. **Warning:** Please note that partial repository checks (i.e. running it with ``--max-duration``) can only perform non-cryptographic checksum checks on the segment files. A full repository check (i.e. without ``--max-duration``) can also do a repository index check. Enabling partial repository checks excepts archive checks for the same reason. Therefore partial checks may be useful with very large repositories only where a full check would take too long. The ``--verify-data`` option will perform a full integrity verification (as opposed to checking the CRC32 of the segment) of data, which means reading the data from the repository, decrypting and decompressing it. It is a complete cryptographic verification and hence very time consuming, but will detect any accidental and malicious corruption. Tamper-resistance is only guaranteed for encrypted repositories against attackers without access to the keys. You can not use ``--verify-data`` with ``--repository-only``. About repair mode +++++++++++++++++ The check command is a readonly task by default. If any corruption is found, Borg will report the issue and proceed with checking. To actually repair the issues found, pass ``--repair``. .. note:: ``--repair`` is a **POTENTIALLY DANGEROUS FEATURE** and might lead to data loss! This does not just include data that was previously lost anyway, but might include more data for kinds of corruption it is not capable of dealing with. **BE VERY CAREFUL!** Pursuant to the previous warning it is also highly recommended to test the reliability of the hardware running Borg with stress testing software. This especially includes storage and memory testers. Unreliable hardware might lead to additional data loss. It is highly recommended to create a backup of your repository before running in repair mode (i.e. running it with ``--repair``). Repair mode will attempt to fix any corruptions found. Fixing corruptions does not mean recovering lost data: Borg can not magically restore data lost due to e.g. a hardware failure. Repairing a repository means sacrificing some data for the sake of the repository as a whole and the remaining data. Hence it is, by definition, a potentially lossy task. In practice, repair mode hooks into both the repository and archive checks: 1. When checking the repository's consistency, repair mode will try to recover as many objects from segments with integrity errors as possible, and ensure that the index is consistent with the data stored in the segments. 2. When checking the consistency and correctness of archives, repair mode might remove whole archives from the manifest if their archive metadata chunk is corrupt or lost. On a chunk level (i.e. the contents of files), repair mode will replace corrupt or lost chunks with a same-size replacement chunk of zeroes. If a previously zeroed chunk reappears, repair mode will restore this lost chunk using the new chunk. Lastly, repair mode will also delete orphaned chunks (e.g. caused by read errors while creating the archive). Most steps taken by repair mode have a one-time effect on the repository, like removing a lost archive from the repository. However, replacing a corrupt or lost chunk with an all-zero replacement will have an ongoing effect on the repository: When attempting to extract a file referencing an all-zero chunk, the ``extract`` command will distinctly warn about it. The FUSE filesystem created by the ``mount`` command will reject reading such a "zero-patched" file unless a special mount option is given. As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in repair mode, if all its previously lost chunks reappear (e.g. via a later backup). This is achieved by Borg not only keeping track of the all-zero replacement chunks, but also by keeping metadata about the lost chunks. In repair mode Borg will check whether a previously lost chunk reappeared and will replace the all-zero replacement chunk by the reappeared chunk. If all lost chunks of a "zero-patched" file reappear, this effectively "heals" the file. Consequently, if lost chunks were repaired earlier, it is advised to run ``--repair`` a second time after creating some new backups. r4zverify repositoryrz-repository or archive to check consistency ofz--repository-onlyr0rzonly perform repository checksrz--archives-onlyr3zonly perform archives checksz --verify-datar/z`perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)z--repairr'z+attempt to repair any inconsistencies foundz --save-spacer(z!work slower, but using less spacez--max-durationrr)rzJdo only a partial repo check for max. SECONDS seconds (Default: unlimited)ra This command frees repository space by compacting segments. Use this regularly to avoid running out of space - you do not need to use this after each borg command though. It is especially useful after deleting archives, because only compaction will really free repository space. borg compact does not need a key, so it is possible to invoke it from the client or also from the server. Depending on the amount of segments that need compaction, it may take a while, so consider using the ``--progress`` option. A segment is compacted if the amount of saved space is above the percentage value given by the ``--threshold`` option. If omitted, a threshold of 10% is used. When using ``--verbose``, borg will output an estimate of the freed space. After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits`` to clean up the numerous 17byte commit-only segments that borg 1.1 did not clean up due to a bug. It is enough to do that once per repository. After cleaning up the commits, borg will also do a normal compaction. See :ref:`separate_compaction` in Additional Notes for more details. rz*compact segment files / free space in repozrepository to compactz--cleanup-commitsrz)cleanup commit-only 17-byte segment filesz --thresholdPERCENTrrrz>set minimum threshold for saved space in PERCENT (Default: 10)a This command gets and sets options in a local repository or cache config file. For security reasons, this command only works on local repositories. To delete a config value entirely, use ``--delete``. To list the values of the configuration file or the default values, use ``--list``. To get and existing key, pass only the key name. To set a key, pass both the key name and the new value. Keys can be specified in the format "section.name" or simply "name"; the section will default to "repository" and "cache" for the repo and cache configs, respectively. By default, borg config manipulates the repository config file. Using ``--cache`` edits the repository cache's config file instead. rz get and set configuration valuesz-cz--cacherz&get and set values from the repo cachez-dz--deleterOz#delete the key from the config filez-lz--listrz"list the configuration of the repor)rrzrepository to configurerrzname of config key)rrrr"ZVALUEznew value for keyai& This command creates a backup archive containing all files found while recursively traversing all paths specified. Paths are added to the archive as they are given, that means if relative paths are desired, the command has to be run from the correct directory. When giving '-' as path, borg will read data from standard input and create a file 'stdin' in the created archive from that data. In some cases it's more appropriate to use --content-from-command, however. See section *Reading from stdin* below for details. The archive will consume almost no disk space for files or parts of files that have already been stored in other archives. The archive name needs to be unique. It must not end in '.checkpoint' or '.checkpoint.N' (with N being a number), because these names are used for checkpoints and treated in special ways. In the archive name, you may use the following placeholders: {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others. Backup speed is increased by not reprocessing files that are already part of existing archives and weren't modified. The detection of unmodified files is done by comparing multiple file metadata values with previous values kept in the files cache. This comparison can operate in different modes as given by ``--files-cache``: - ctime,size,inode (default) - mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4) - ctime,size (ignore the inode number) - mtime,size (ignore the inode number) - rechunk,ctime (all files are considered modified - rechunk, cache ctime) - rechunk,mtime (all files are considered modified - rechunk, cache mtime) - disabled (disable the files cache, all files considered modified - rechunk) inode number: better safety, but often unstable on network filesystems Normally, detecting file modifications will take inode information into consideration to improve the reliability of file change detection. This is problematic for files located on sshfs and similar network file systems which do not provide stable inode numbers, such files will always be considered modified. You can use modes without `inode` in this case to improve performance, but reliability of change detection might be reduced. ctime vs. mtime: safety vs. speed - ctime is a rather safe way to detect changes to a file (metadata and contents) as it can not be set from userspace. But, a metadata-only change will already update the ctime, so there might be some unnecessary chunking/hashing even without content changes. Some filesystems do not support ctime (change time). E.g. doing a chown or chmod to a file will change its ctime. - mtime usually works and only updates if file contents were changed. But mtime can be arbitrarily set from userspace, e.g. to set mtime back to the same value it had before a content change happened. This can be used maliciously as well as well-meant, but in both cases mtime based cache modes can be problematic. The mount points of filesystems or filesystem snapshots should be the same for every creation of a new archive to ensure fast operation. This is because the file cache that is used to determine changed files quickly uses absolute filenames. If this is not possible, consider creating a bind mount to a stable location. The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated (O, C and D, respectively), then the Number of files (N) processed so far, followed by the currently processed path. When using ``--stats``, you will get some statistics about how much data was added - the "This Archive" deduplicated size there is most interesting as that is how much your repository will grow. Please note that the "All archives" stats refer to the state after creation. Also, the ``--stats`` and ``--dry-run`` options are mutually exclusive because the data is not actually compressed and deduplicated during a dry run. For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. For more help on placeholders, see the :ref:`borg_placeholders` command output. .. man NOTES The ``--exclude`` patterns are not like tar. In tar ``--exclude`` .bundler/gems will exclude foo/.bundler/gems. In borg it will not, you need to use ``--exclude`` '\*/.bundler/gems' to get the same effect. In addition to using ``--exclude`` patterns, it is possible to use ``--exclude-if-present`` to specify the name of a filesystem object (e.g. a file or folder name) which, when contained within another folder, will prevent the containing folder from being backed up. By default, the containing folder and all of its contents will be omitted from the backup. If, however, you wish to only include the objects specified by ``--exclude-if-present`` in your backup, and not include any other contents of the containing folder, this can be enabled through using the ``--keep-exclude-tags`` option. The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them). It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different from the device number of their parent. In general: be aware that there are directories with device number different from their parent, which the kernel does not consider a mountpoint and also the other way around. Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). macOS examples are the apfs mounts of a typical macOS installation. Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended. .. _list_item_flags: Item flags ++++++++++ ``--list`` outputs a list of all files, directories and other file system items it considered (no matter whether they had content changes or not). For each item, it prefixes a single-letter flag that indicates type and/or status of the item. If you are interested only in a subset of that output, you can give e.g. ``--filter=AME`` and it will only show regular files with A, M or E status (see below). A uppercase character represents the status of a regular file relative to the "files" cache (not relative to the repo -- this is an issue if the files cache is not used). Metadata is stored in any case and for 'A' and 'M' also new data chunks are stored. For 'U' all data chunks refer to already existing chunks. - 'A' = regular file, added (see also :ref:`a_status_oddity` in the FAQ) - 'M' = regular file, modified - 'U' = regular file, unchanged - 'C' = regular file, it changed while we backed it up - 'E' = regular file, an error happened while accessing/reading *this* file A lowercase character means a file type other than a regular file, borg usually just stores their metadata: - 'd' = directory - 'b' = block device - 'c' = char device - 'h' = regular file, hardlink (to already seen inodes) - 's' = symlink - 'f' = fifo Other flags used include: - 'i' = backup data was read from standard input (stdin) - '-' = dry run, item was *not* backed up - 'x' = excluded, item was *not* backed up - '?' = missing status code (if you see this, please file a bug report!) Reading from stdin ++++++++++++++++++ There are two methods to read from stdin. Either specify ``-`` as path and pipe directly to borg:: backup-vm --id myvm --stdout | borg create REPO::ARCHIVE - Or use ``--content-from-command`` to have Borg manage the execution of the command and piping. If you do so, the first PATH argument is interpreted as command to execute and any further arguments are treated as arguments to the command:: borg create --content-from-command REPO::ARCHIVE -- backup-vm --id myvm --stdout ``--`` is used to ensure ``--id`` and ``--stdout`` are **not** considered arguments to ``borg`` but rather ``backup-vm``. The difference between the two approaches is that piping to borg creates an archive even if the command piping to borg exits with a failure. In this case, **one can end up with truncated output being backed up**. Using ``--content-from-command``, in contrast, borg is guaranteed to fail without creating an archive should the command fail. The command is considered failed when it returned a non-zero exit code. Reading from stdin yields just a stream of data without file metadata associated with it, and the files cache is not needed at all. So it is safe to disable it via ``--files-cache disabled`` and speed up backup creation a bit. By default, the content read from stdin is stored in a file called 'stdin'. Use ``--stdin-name`` to change the name. rz create backupz-nrRrzdo not create a backup archivez-sz--statsrz(print statistics for the created archiverz/output verbose list of items (files, dirs, ...)z--filterZ STATUSCHARSrzEonly display items with the given status characters (see description))rrrrz--jsonz*output stats as JSON. Implies ``--stats``.rz--no-cache-syncrzNexperimental: do not synchronize the cache. Implies not using the files cache.z --stdin-namerrz9use NAME in archive for stdin data (default: %(default)r)rz --stdin-userZUSERrz>set user USER in archive for stdin data (default: %(default)r)z --stdin-groupZGROUPrz@set group GROUP in archive for stdin data (default: %(default)r)z --stdin-moderrcSrrrrrrrrDMrz'Archiver.build_parser..z@set mode to M in archive for stdin data (default: %(default)04o)z--content-from-commandzZinterpret PATH as command and store its stdout. See also section Reading from stdin below.z--paths-from-stdinzread DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less.z--paths-from-commandzHinterpret PATH as command and treat its output as ``--paths-from-stdin``z--paths-delimiterZDELIMz\set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``))rz--exclude-nodumprzexclude files flagged NODUMPzFilesystem optionsz-xz--one-file-systemrzstay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below.rrrrz-only store numeric user and group identifiersrrzdo not store atime into archivez--atimerzdo store atime into archivez --noctimerzdo not store ctime into archivez --nobirthtimerz3do not store birthtime (creation date) into archiverrz%deprecated, use ``--noflags`` insteadz --noflagsrzAdo not read and store flags (e.g. NODUMP, IMMUTABLE) into archivez--noaclsrz'do not read and store ACLs into archivez --noxattrsrz)do not read and store xattrs into archivez--sparserz>detect sparse holes in input (supported only by fixed chunker)z --files-cacheZMODErz(operate files cache in MODE. default: %s)rrrrrrz--read-specialrzopen and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.zArchive optionsz --commentrCOMMENTz!add a comment text to the archive)rrrrrz --timestamp TIMESTAMPrJzmanually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.z--checkpoint-intervalriz6write checkpoint every SECONDS seconds (Default: 1800)z--chunker-paramsZPARAMSrz~specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: %s,%d,%d,%d,%d)rrrrrrz-Cz --compressionZ COMPRESSIONrlz4z`select compression algorithm, see the output of the "borg help compression" command for details.ZARCHIVEz?name of archive to create (must be also a valid directory name)rr rzpaths to archive)rrrrral These commands are not intended for normal use and potentially very dangerous if used incorrectly. They exist to improve debugging capabilities without direct system access, e.g. in case you ever run into some severe malfunction. Use them only if you know what you are doing or if a trusted developer tells you what to do.rz/debugging command (not intended for normal use)z This command displays some system information that might be useful for bug reports and debugging problems. If a traceback happens, this information is already appended at the end of the traceback. rz5show system infos for debugging / bug reports (debug)zq This command dumps raw (but decrypted and decompressed) archive items (only metadata) to files. zdump-archive-itemsz%dump archive items (metadata) (debug)zarchive to dumpz\ This command dumps all metadata of an archive in a decoded form to a file. z dump-archivez%dump decoded archive metadata (debug)zfile to dump data intozc This command dumps manifest metadata of a repository in a decoded form to a file. z dump-manifestz(dump decoded repository metadata (debug)zrepository to dumpz` This command dumps raw (but decrypted and decompressed) repo objects to files. zdump-repo-objszdump repo objects (debug)z--ghostrXzRdump all segment file contents, including deleted/uncommitted objects and commits.z --segmentZSEGrMz>used together with --ghost: limit processing to given segment.rz--offsetZOFFSrNz=used together with --ghost: limit processing to given offset.zx This command searches raw (but decrypted and decompressed) repo objects for a specific bytes sequence. zsearch-repo-objszsearch repo objects (debug)zrepository to searchr^ZWANTEDzCterm to search the repo for, either 0x1234abcd hex term or a stringzJ This command computes the id-hash for some file content. zid-hashz-compute id-hash for some file content (debug)zrepository to usez0content for which the id-hash shall get computedzB This command gets an object from the repository. zget-objz"get object from repository (debug)rKIDz"hex object ID to get from the repozfile to write object data intozB This command puts an object into the repository. zput-objz put object to repository (debug)z"hex object ID to put into the repoz#file to read and create object fromzC This command deletes objects from the repository. z delete-objz%delete object from repository (debug)rZZIDs+z(hex object ID(s) to delete from the reporz\ This command displays the reference count for objects from the repository. z refcount-objz0show refcount for object from repository (debug)z&hex object ID(s) to show refcounts forz? This command dumps the repository hints data. z dump-hintszdump repo hints (debug)zQ Convert a Borg profile to a Python cProfile compatible profile. zconvert-profilez.convert Borg profile to Python profile (debug)rZINPUTrz Borg profiler$ZOUTPUTr5z Output fileaB This command deletes an archive from the repository or the complete repository. Important: When deleting archives, repository disk space is **not** freed until you run ``borg compact``. When you delete a complete repository, the security info and local cache for it (if any) are also deleted. Alternatively, you can delete just the local cache with the ``--cache-only`` option, or keep the security info with the ``--keep-security-info`` option. When in doubt, use ``--dry-run --list`` to see what would be deleted. When using ``--stats``, you will get some statistics about how much data was deleted - the "Deleted data" deduplicated size there is most interesting as that is how much your repository will shrink. Please note that the "All archives" stats refer to the state after deletion. You can delete multiple archives by specifying a shell pattern to match multiple archives using the ``--glob-archives GLOB`` option (for more info on these patterns, see :ref:`borg_patterns`). To avoid accidentally deleting archives, especially when using glob patterns, it might be helpful to use the ``--dry-run`` to test out the command without actually making any changes to the repository. zdelete archivezdo not change repositoryzoutput verbose list of archivesz(print statistics for the deleted archivez --cache-onlyrz4delete only the local cache for the given repositoryz--forcerrjz`force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.rz--keep-security-inforz7keep the local security info when deleting a repositoryzrepository or archive to deleterzarchives to deletea This command finds differences (file contents, user/group/mode) between archives. A repository location and an archive name must be specified for REPO::ARCHIVE1. ARCHIVE2 is just another archive name in same repository (no repository location allowed). For archives created with Borg 1.1 or newer diff automatically detects whether the archives are created with the same chunker params. If so, only chunk IDs are compared, which is very fast. For archives prior to Borg 1.1 chunk contents are compared by default. If you did not create the archives with different chunker params, pass ``--same-chunker-params``. Note that the chunker params changed from Borg 0.xx to 1.0. For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. rmz$find differences in archive contentsz0only consider numeric user and group identifiersz--same-chunker-paramsrxz%Override check of chunker parameters.z--sortryz#Sort the output lines by file path.z--content-onlyzBOnly compare differences in content (exclude metadata differences)z --json-lineszFormat output as JSON Lines. zREPO::ARCHIVE1z%repository location and ARCHIVE1 namervZARCHIVE2z.ARCHIVE2 name (no repository location allowed)zEpaths of items inside the archives to compare; patterns are supportedaJ This command creates a tarball from an archive. When giving '-' as the output FILE, Borg will write a tar stream to standard output. By default (``--tar-filter=auto``) Borg will detect whether the FILE should be compressed based on its file extension and pipe the tarball through an appropriate filter before writing it to FILE: - .tar.gz or .tgz: gzip - .tar.bz2 or .tbz: bzip2 - .tar.xz or .txz: xz - .tar.zstd or .tar.zst: zstd - .tar.lz4: lz4 Alternatively, a ``--tar-filter`` program may be explicitly specified. It should read the uncompressed tar stream from stdin and write a compressed/filtered tar stream to stdout. The generated tarball uses the GNU tar format. export-tar is a lossy conversion: BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported. Timestamp resolution is limited to whole seconds, not the nanosecond resolution otherwise supported by Borg. A ``--sparse`` option (as found in borg extract) is not supported. By default the entire archive is extracted but a subset of files and directories can be selected by passing a list of ``PATHs`` as arguments. The file selection can further be restricted by using the ``--exclude`` option. For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. ``--progress`` can be slower than no progress display, since it makes one additional pass over the archive metadata. z export-tarzcreate tarball from archivez --tar-filterr8r2z#filter program to pipe data through)rrrzarchive to exportr9rz0output tar file. "-" to write to stdout instead.rra This command extracts the contents of an archive. By default the entire archive is extracted but a subset of files and directories can be selected by passing a list of ``PATHs`` as arguments. The file selection can further be restricted by using the ``--exclude`` option. For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. By using ``--dry-run``, you can do all extraction steps except actually writing the output data: reading metadata and data chunks from the repo, checking the hash/hmac, decrypting, decompressing. ``--progress`` can be slower than no progress display, since it makes one additional pass over the archive metadata. .. note:: Currently, extract always writes into the current working directory ("."), so make sure you ``cd`` to the right place before calling ``borg extract``. When parent directories are not extracted (because of using file/directory selection or any other reason), borg can not restore parent directories' metadata, e.g. owner, group, permission, etc. rQzextract archive contentsz do not actually change any filesz,only obey numeric user and group identifiersz1do not extract/set flags (e.g. NODUMP, IMMUTABLE)zdo not extract/set ACLszdo not extract/set xattrsz--stdoutrz"write all extracted data to stdoutz7create holes in output sparse file from all-zero chunkszarchive to extractrz Extra help)rrrz --epilog-onlyr)rrz --usage-onlyrrrzadditional help on TOPIC)rrrra{ This command displays detailed information about the specified archive or repository. Please note that the deduplicated sizes of the individual archives do not add up to the deduplicated size of the repository ("all archives"), because the two are meaning different things: This archive / deduplicated size = amount of data stored ONLY for this archive = unique chunks of this archive. All archives / deduplicated size = amount of data stored in the repo = all chunks in the repository. Borg archives can only contain a limited amount of file metadata. The size of an archive relative to this limit depends on a number of factors, mainly the number of files, the lengths of paths and other metadata stored for files. This is shown as *utilization of maximum supported archive size*. z&show repository or archive informationz2repository or archive to display information aboutzformat output as JSONa/ This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. Encryption mode TLDR ++++++++++++++++++++ The encryption mode can only be configured when creating a new repository - you can neither configure it on a per-archive basis nor change the encryption mode of an existing repository. Use ``repokey``:: borg init --encryption repokey /path/to/repo Or ``repokey-blake2`` depending on which is faster on your client machines (see below):: borg init --encryption repokey-blake2 /path/to/repo Borg will: 1. Ask you to come up with a passphrase. 2. Create a borg key (which contains 3 random secrets. See :ref:`key_files`). 3. Encrypt the key with your passphrase. 4. Store the encrypted borg key inside the repository directory (in the repo config). This is why it is essential to use a secure passphrase. 5. Encrypt and sign your backups to prevent anyone from reading or forging them unless they have the key and know the passphrase. Make sure to keep a backup of your key **outside** the repository - do not lock yourself out by "leaving your keys inside your car" (see :ref:`borg_key_export`). For remote backups the encryption is done locally - the remote machine never sees your passphrase, your unencrypted key or your unencrypted files. Chunking and id generation are also based on your key to improve your privacy. 6. Use the key when extracting files to decrypt them and to verify that the contents of the backups have not been accidentally or maliciously altered. Picking a passphrase ++++++++++++++++++++ Make sure you use a good passphrase. Not too short, not too simple. The real encryption / decryption key is encrypted with / locked by your passphrase. If an attacker gets your key, he can't unlock and use it without knowing the passphrase. Be careful with special or non-ascii characters in your passphrase: - Borg processes the passphrase as unicode (and encodes it as utf-8), so it does not have problems dealing with even the strangest characters. - BUT: that does not necessarily apply to your OS / VM / keyboard configuration. So better use a long passphrase made from simple ascii chars than one that includes non-ascii stuff or characters that are hard/impossible to enter on a different keyboard layout. You can change your passphrase for existing repos at any time, it won't affect the encryption/decryption key or other secrets. More encryption modes +++++++++++++++++++++ Only use ``--encryption none`` if you are OK with anyone who has access to your repository being able to read your backups and tamper with their contents without you noticing. If you want "passphrase and having-the-key" security, use ``--encryption keyfile``. The key will be stored in your home directory (in ``~/.config/borg/keys``). If you do **not** want to encrypt the contents of your backups, but still want to detect malicious tampering use ``--encryption authenticated``. To normally work with ``authenticated`` repos, you will need the passphrase, but there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs. If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``, ``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups the hashing is done on your local machine. .. nanorst: inline-fill +----------+---------------+------------------------+--------------------------+ | Hash/MAC | Not encrypted | Not encrypted, | Encrypted (AEAD w/ AES) | | | no auth | but authenticated | and authenticated | +----------+---------------+------------------------+--------------------------+ | SHA-256 | none | `authenticated` | repokey | | | | | keyfile | +----------+---------------+------------------------+--------------------------+ | BLAKE2b | n/a | `authenticated-blake2` | `repokey-blake2` | | | | | `keyfile-blake2` | +----------+---------------+------------------------+--------------------------+ .. nanorst: inline-replace Modes `marked like this` in the above table are new in Borg 1.1 and are not backwards-compatible with Borg 1.0.x. On modern Intel/AMD CPUs (except very cheap ones), AES is usually hardware-accelerated. BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs (except AMD Ryzen and future CPUs with SHA extensions), which makes `authenticated-blake2` faster than `none` and `authenticated`. On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster than BLAKE2b-256 there. NEON accelerates AES as well. Hardware acceleration is always used automatically when available. `repokey` and `keyfile` use AES-CTR-256 for encryption and HMAC-SHA256 for authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash is HMAC-SHA256 as well (with a separate key). These modes are compatible with Borg 1.0.x. `repokey-blake2` and `keyfile-blake2` are also authenticated encryption modes, but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID hash is a keyed BLAKE2b-256 hash. These modes are new and *not* compatible with Borg 1.0.x. `authenticated` mode uses no encryption, but authenticates repository contents through the same HMAC-SHA256 hash as the `repokey` and `keyfile` modes (it uses it as the chunk ID hash). The key is stored like `repokey`. This mode is new and *not* compatible with Borg 1.0.x. `authenticated-blake2` is like `authenticated`, but uses the keyed BLAKE2b-256 hash from the other blake2 modes. This mode is new and *not* compatible with Borg 1.0.x. `none` mode uses no encryption and no authentication. It uses SHA256 as chunk ID hash. This mode is not recommended, you should rather consider using an authenticated or authenticated/encrypted mode. This mode has possible denial-of-service issues when running ``borg create`` on contents controlled by an attacker. Use it only for new repositories where no encryption is wanted **and** when compatibility with 1.0.x is important. If compatibility with 1.0.x is not important, use `authenticated-blake2` or `authenticated` instead. This mode is compatible with Borg 1.0.x. initzinitialize empty repositoryzrepository to createrz --encryptionrz)select encryption key mode **(required)**)rrrequiredchoicesrz --append-onlyrzcreate an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.z--storage-quotaZQUOTArzKSet storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.z--make-parent-dirsrzOcreate the parent directories of the repository directory, if they are missing.rz+Manage a keyfile or repokey of a repositoryzmanage repository keyaG If repository encryption is used, the repository is inaccessible without the key. This command allows one to backup this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. There are three backup formats. The normal backup format is suitable for digital storage as a file. The ``--paper`` backup format is optimized for printing and typing in while importing, with per line checks to reduce problems with manual input. The ``--qr-html`` creates a printable HTML template with a QR code and a copy of the ``--paper``-formatted key. For repositories using keyfile encryption the key is saved locally on the system that is capable of doing backups. To guard against loss of this key, the key needs to be backed up independently of the main data backup. For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file is damaged for some reason. Examples:: borg key export /path/to/repo > encrypted-key-backup borg key export --paper /path/to/repo > encrypted-key-backup.txt borg key export --qr-html /path/to/repo > encrypted-key-backup.html # Or pass the output file as an argument instead of redirecting stdout: borg key export /path/to/repo encrypted-key-backup borg key export --paper /path/to/repo encrypted-key-backup.txt borg key export --qr-html /path/to/repo encrypted-key-backup.html r?z export repository key for backup)rrrrzwhere to store the backupz--paperr=z8Create an export suitable for printing and later type-inz --qr-htmlr>zFCreate an html file suitable for printing and later type-in or qr scana This command restores a key previously backed up with the export command. If the ``--paper`` option is given, the import will be an interactive process in which each line is checked for plausibility before proceeding to the next line. For this format PATH must not be given. For repositories using keyfile encryption, the key file which ``borg key import`` writes to depends on several factors. If the ``BORG_KEY_FILE`` environment variable is set and non-empty, ``borg key import`` creates or overwrites that file named by ``$BORG_KEY_FILE``. Otherwise, ``borg key import`` searches in the ``$BORG_KEYS_DIR`` directory for a key file associated with the repository. If a key file is found in ``$BORG_KEYS_DIR``, ``borg key import`` overwrites it; otherwise, ``borg key import`` creates a new key file in ``$BORG_KEYS_DIR``. importz!import repository key from backupz+path to the backup ('-' to read from stdin)z8interactively import from a backup done with ``--paper``a The key files used for repository encryption are optionally passphrase protected. This command can be used to change this passphrase. Please note that this command only changes the passphrase, but not any secret protected by it (like e.g. encryption/MAC keys or chunker seed). Thus, changing the passphrase after passphrase and borg key got compromised does not protect future (nor past) backups to the same repository. zchange-passphrasezchange repository passphrasea This command migrates a repository from passphrase mode (removed in Borg 1.0) to repokey mode. You will be first asked for the repository passphrase (to open it in passphrase mode). This is the same passphrase as you used to use for this repo before 1.0. It will then derive the different secrets from this passphrase. Then you will be asked for a new passphrase (twice, for safety). This passphrase will be used to protect the repokey (which contains these same secrets in encrypted form). You may use the same passphrase as you used to use, but you may also use a different one. After migrating to repokey mode, you can change the passphrase at any time. But please note: the secrets will always stay the same and they could always be derived from your (old) passphrase-mode passphrase. zmigrate-to-repokeyz-migrate passphrase-mode repository to repokeyah This command lists the contents of a repository or an archive. For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. .. man NOTES The FORMAT specifier syntax +++++++++++++++++++++++++++ The ``--format`` option uses python's `format string syntax `_. Examples: :: $ borg list --format '{archive}{NL}' /path/to/repo ArchiveFoo ArchiveBar ... # {VAR:NUMBER} - pad to NUMBER columns. # Strings are left-aligned, numbers are right-aligned. # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded. $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274] $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo ... # {VAR:NUMBER} - pad to NUMBER columns right-aligned. $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo ... The following keys are always available: zN Keys available only when listing archives in a repository: zI Keys available only when listing files in an archive: z#list archive or repository contentsrrrrz--shortrz-only print file/directory names, nothing elsez--formatZFORMATr@zspecify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")raOnly valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.aOnly valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.z)repository or archive to list contents ofz%paths to list; patterns are supportedra The prune command prunes a repository by deleting all archives not matching any of the specified retention options. Important: Repository disk space is **not** freed until you run ``borg compact``. This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. This retention policy is commonly referred to as `GFS `_ (Grandfather-father-son) backup rotation scheme. Also, prune automatically removes checkpoint archives (incomplete archives left behind by interrupted backup runs) except if the checkpoint is the latest archive (and thus still needed). Checkpoint archives are not considered when comparing archive counts against the retention limits (``--keep-X``). If a prefix is set with -P, then only archives that start with the prefix are considered for deletion and only those archives count towards the totals specified by the rules. Otherwise, *all* archives in the repository are candidates for deletion! There is no automatic distinction between archives representing different contents. These need to be distinguished by specifying matching prefixes. If you have multiple sequences of archives with different data sets (e.g. from different machines) in one shared repository, use one prune call per data set that matches only the respective archives using the -P option. The ``--keep-within`` option takes an argument of the form "", where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means to keep all archives that were created within the past 48 hours. "1m" is taken to mean "31d". The archives kept with this option do not count towards the totals specified by any other options. A good procedure is to thin out more and more the older your backups get. As an example, ``--keep-daily 7`` means to keep the latest backup on each day, up to 7 most recent days with backups (days without backups do not count). The rules are applied from secondly to yearly, and backups selected by previous rules do not count towards those of later rules. The time that each backup starts is used for pruning purposes. Dates and times are interpreted in the local timezone, and weeks go from Monday to Sunday. Specifying a negative number of archives to keep means that there is no limit. As of borg 1.2.0, borg will retain the oldest archive if any of the secondly, minutely, hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet its retention target. This enables the first chronological archive to continue aging until it is replaced by a newer archive that meets the retention criteria. The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will keep the last N archives under the assumption that you do not create more than one backup archive in the same second). When using ``--stats``, you will get some statistics about how much data was deleted - the "Deleted data" deduplicated size there is most interesting as that is how much your repository will shrink. Please note that the "All archives" stats refer to the state after pruning. rzprune archivesz_force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.z/output verbose list of archives it keeps/prunesz --keep-withinZINTERVALrz+keep all archives within this time intervalrz --keep-lastz--keep-secondlyrz#number of secondly archives to keep)rrrrz--keep-minutelyrz#number of minutely archives to keepz-Hz --keep-hourlyrz!number of hourly archives to keepz --keep-dailyrz number of daily archives to keepz-wz --keep-weeklyrz!number of weekly archives to keepz-mz--keep-monthlyrz"number of monthly archives to keepz-yz --keep-yearlyrz!number of yearly archives to keepzrepository to prunea7 Recreate the contents of existing archives. recreate is a potentially dangerous function and might lead to data loss (if used wrongly). BE VERY CAREFUL! Important: Repository disk space is **not** freed until you run ``borg compact``. ``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags`` and PATH have the exact same semantics as in "borg create", but they only check for files in the archives and not in the local file system. If PATHs are specified, the resulting archives will only contain files from these PATHs. Note that all paths in an archive are relative, therefore absolute patterns/paths will *not* match (``--exclude``, ``--exclude-from``, PATHs). ``--recompress`` allows one to change the compression of existing data in archives. Due to how Borg stores compressed size information this might display incorrect information for archives that were not recreated at the same time. There is no risk of data loss by this. ``--chunker-params`` will re-chunk all files in the archive, this can be used to have upgraded Borg 0.xx or Attic archives deduplicate with Borg 1.x archives. **USE WITH CAUTION.** Depending on the PATHs and patterns given, recreate can be used to permanently delete files from archives. When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are interpreted. See :ref:`list_item_flags` in ``borg create`` for details. The archive being recreated is only removed after the operation completes. The archive that is built during the operation exists at the same time at ".recreate". The new archive will have a different archive ID. With ``--target`` the original archive is not replaced, instead a new archive is created. When rechunking (or recompressing), space usage can be substantial - expect at least the entire deduplicated size of the archives using the previous chunker (or compression) params. If you recently ran borg check --repair and it had to fix lost chunks with all-zero replacement chunks, please first run another backup for the same data and re-run borg check --repair afterwards to heal any archives that had lost chunks which are still generated from the input data. Important: running borg recreate to re-chunk will remove the chunks_healthy metadata of all items with replacement chunks, so healing will not be possible any more after re-chunking (it is also unlikely it would ever work: due to the change of chunking parameters, the missing chunk likely will never be seen again even if you still have the data that produced it). rzRonly display items with the given status characters (listed in borg create --help)zdo not change anythingzprint statistics at endz--targetrJZTARGETzocreate a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive))rrrrr)rrrrrzmanually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.z --recompressrr if-different)rrrarecompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered); `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never".)rrrrrrrzrechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunkz!repository or archive to recreatez)paths to recreate; patterns are supportedzu This command renames an archive in the repository. This results in a different archive ID. r|zrename archivezarchive to renameZNEWNAMEzthe new archive name to usezm This command starts a repository server process. This command is usually not used manually. r zstart repository server processz--restrict-to-pathr r)zrestrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.z--restrict-to-repositoryr arestrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.zonly allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.zOverride storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.z This command un-mounts a FUSE filesystem that was mounted with ``borg mount``. This is a convenience wrapper that just calls the platform-specific shell command - usually this is either umount or fusermount -u. rizumount repositoryrrz&mountpoint of the filesystem to umountal Upgrade an existing, local Borg repository. When you do not need borg upgrade +++++++++++++++++++++++++++++++++ Not every change requires that you run ``borg upgrade``. You do **not** need to run it when: - moving your repository to a different place - upgrading to another point release (like 1.0.x to 1.0.y), except when noted otherwise in the changelog - upgrading from 1.0.x to 1.1.x, except when noted otherwise in the changelog Borg 1.x.y upgrades +++++++++++++++++++ Archive TAM authentication: Use ``borg upgrade --archives-tam REPO`` to add archive TAMs to all archives that are not TAM authenticated yet. This is a convenient method to just trust all archives present - if an archive does not have TAM authentication yet, a TAM will be added. Archives created by old borg versions < 1.0.9 do not have TAMs. Archives created by newer borg version should have TAMs already. If you have a high risk environment, you should not just run this, but first verify that the archives are authentic and not malicious (== have good content, have a good timestamp). Borg 1.2.5+ needs all archives to be TAM authenticated for safety reasons. This upgrade needs to be done once per repository. Manifest TAM authentication: Use ``borg upgrade --tam REPO`` to require manifest authentication introduced with Borg 1.0.9 to address security issues. This means that modifying the repository after doing this with a version prior to 1.0.9 will raise a validation error, so only perform this upgrade after updating all clients using the repository to 1.0.9 or newer. This upgrade should be done on each client for safety reasons. If a repository is accidentally modified with a pre-1.0.9 client after this upgrade, use ``borg upgrade --tam --force REPO`` to remedy it. If you routinely do this you might not want to enable this upgrade (which will leave you exposed to the security issue). You can reverse the upgrade by issuing ``borg upgrade --disable-tam REPO``. See https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability for details. Attic and Borg 0.xx to Borg 1.x +++++++++++++++++++++++++++++++ This currently supports converting an Attic repository to Borg and also helps with converting Borg 0.xx to 1.0. Currently, only LOCAL repositories can be upgraded (issue #465). Please note that ``borg create`` (since 1.0.0) uses bigger chunks by default than old borg or attic did, so the new chunks won't deduplicate with the old chunks in the upgraded repository. See ``--chunker-params`` option of ``borg create`` and ``borg recreate``. ``borg upgrade`` will change the magic strings in the repository's segments to match the new Borg magic strings. The keyfiles found in $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and copied to $BORG_KEYS_DIR or ~/.config/borg/keys. The cache files are converted, from $ATTIC_CACHE_DIR or ~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the cache layout between Borg and Attic changed, so it is possible the first backup after the conversion takes longer than expected due to the cache resync. Upgrade should be able to resume if interrupted, although it will still iterate over all segments. If you want to start from scratch, use `borg delete` over the copied repository to make sure the cache files are also removed:: borg delete borg Unless ``--inplace`` is specified, the upgrade process first creates a backup copy of the repository, in REPOSITORY.before-upgrade-DATETIME, using hardlinks. This requires that the repository and its parent directory reside on same filesystem so the hardlink copy can work. This takes longer than in place upgrades, but is much safer and gives progress information (as opposed to ``cp -al``). Once you are satisfied with the conversion, you can safely destroy the backup copy. WARNING: Running the upgrade in place will make the current copy unusable with older version, with no way of going back to previous versions. This can PERMANENTLY DAMAGE YOUR REPOSITORY! Attic CAN NOT READ BORG REPOSITORIES, as the magic strings have changed. You have been warned.rzupgrade repository formatz --inplacerz^rewrite repository in place, with no chance of going back to older versions of the repository.rz Force upgradez--tamrzIEnable manifest authentication (in key and cache) (Borg 1.0.9 and later).z --disable-tamrz3Disable manifest authentication (in key and cache).z--archives-tamrz(add TAM authentication for all archives.z%path to the repository to be upgradeda This command runs a user-specified command while the repository lock is held. It will first try to acquire the lock (make sure that no other operation is running in the repo), then execute the given command as a subprocess and wait for its termination, release the lock and return the user command's return code as borg's return code. .. note:: If you copy a repository with the lock held, the lock will be present in the copy. Thus, before using borg on the copy from a different host, you need to use "borg break-lock" on the copied repository, because Borg is cautious and does not automatically remove stale locks made by a different host. z with-lockzrun user command with lock heldzrepository to lockrZCOMMANDzcommand to runrZARGSzcommand argumentsa This command creates a backup archive from a tarball. When giving '-' as path, Borg will read a tar stream from standard input. By default (--tar-filter=auto) Borg will detect whether the file is compressed based on its file extension and pipe the file through an appropriate filter: - .tar.gz or .tgz: gzip -d - .tar.bz2 or .tbz: bzip2 -d - .tar.xz or .txz: xz -d - .tar.zstd or .tar.zst: zstd -d - .tar.lz4: lz4 -d Alternatively, a --tar-filter program may be explicitly specified. It should read compressed data from stdin and output an uncompressed tar stream on stdout. Most documentation of borg create applies. Note that this command does not support excluding files. import-tar is a lossy conversion: BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported. Timestamp resolution is limited to whole seconds, not the nanosecond resolution otherwise supported by Borg. A ``--sparse`` option (as found in borg create) is not supported. import-tar reads POSIX.1-1988 (ustar), POSIX.1-2001 (pax), GNU tar, UNIX V7 tar and SunOS tar with extended attributes. To import multiple tarballs into a single archive, they can be simply concatenated (e.g. using "cat") into a single file, and imported with an ``--ignore-zeros`` option to skip through the stop markers between them. z import-tar)rrrrz3only display items with the given status characters)rrrrz&output stats as JSON (implies --stats)z--ignore-zerosrz.ignore zero-filled blocks in the input tarball)rrrr)rrrrrrZTARFILEz/input tar file. "-" to read from stdin instead.)[rArgumentParserrrrpartialdo_maincommand_helprrrr rrrrrZRawDescriptionHelpFormatterrrZadd_subparsersZ add_parserrrr1rr5rrr3rrSrrrZSTDIN_MODE_DEFAULTrr9ZFILES_CACHE_MODE_UI_DEFAULTr7rJr3ZCHUNKER_PARAMSr!rr4r:rErHr\r0rernrlrorrrsr}rFileTyperUr{r2r>rVrrrr r#rrCrGr;rLr:Z keys_helprrr<r;rrrFrr}rrrrZ REMAINDERr)9rrrrrZ common_parserZmid_common_parserZ mount_epilog subparsersZbenchmark_epilogrZbenchmark_parsersZbench_crud_epilogZbreak_lock_epilogZ check_epilogZcompact_epilogZ config_epilogrZ create_epilogrZfs_groupZ archive_groupZ debug_epilogZ debug_parsersZdebug_info_epilogZdebug_dump_archive_items_epilogZdebug_dump_archive_epilogZdebug_dump_manifest_epilogZdebug_dump_repo_objs_epilogZdebug_search_repo_objs_epilogZdebug_id_hash_epilogZdebug_get_obj_epilogZdebug_put_obj_epilogZdebug_delete_obj_epilogZdebug_refcount_obj_epilogZdebug_dump_hints_epilogZdebug_convert_profile_epilogZ delete_epilogZ diff_epilogZexport_tar_epilogZextract_epilogZ info_epilogZ init_epilogZ key_parsersZkey_export_epilogZkey_import_epilogZchange_passphrase_epilogZmigrate_to_repokey_epilogZ list_epilogZ prune_epilogZrecreate_epilogZ rename_epilogZ serve_epilogZ umount_epilogZupgrade_epilogZwith_lock_epilogZimport_tar_epilogr)rrrrrr build_parserY s^  7   8   '   r                    4                                                                 %                   #          ' '+ +/ 0   7       4                  c     #          zArchiver.build_parserc Cs||dd}|dur[|j|jkr[t|}ttdd|}||dd}|j|jkr[hd}hd}t}|D]} | |vsJJd| t || |} | |urZt || | q>|S)zWusually, just returns argv, except if we deal with a ssh forced command for borg serve.rNcSsd|vS)N=r)rrrrrDsz#Archiver.get_args..>rrr r r>rrrz*allowlist has denylisted attribute name %s) rTrrrrr itertools dropwhilerrr) rargvcmdr[Z client_argvZ client_resultZdenylistZ allowlistZ not_present attr_namer"rrrget_argss     zArchiver.get_argsc Cs|r||}|}||pdg}|j|t|}||jkr-|jr-|jr-| d||jkrI|jsI|j s;|j rA| dn|jsI| dt |ddsk|j |j|j|j|j|j|j|j|jh }||vrktdt |ddry|j|j|_|S) Nrz/Must not pass PATH with ``--paths-from-stdin``.zNo command given.z Need at least one PATH argument.rTz:Not allowed to bypass locking mechanism for chosen commandrJ)rrrTrrrrSrrrrrrr5r3r{r>rVrrrrr-rZwith_timestamprJ)rrrrZbypass_allowedrrrrT!s.           zArchiver.parse_argscCs|sttt|dSr)rRrSr)rris_serverrr prerun_checks;s zArchiver.prerun_checkscCsJdddddd}|D]\}}||d}t||rdnd q d S) zN turn on INFO level logging for args that imply that they will produce output rborg.output.show-versionborg.output.show-rcrzborg.output.progress)rrrrrFINFOWARNN)r7rrrsetLevel)rrZ option_loggeroptionZ logger_nameZ option_setrrr_setup_implied_loggingBs zArchiver._setup_implied_loggingcCs<|jD]}d|vr d|}td|t|dqdS)z9Turn on DEBUG level logging for specified --debug-topics.r(z borg.debug.zEnabling debug topic %sDEBUGN)rrrrrr)rrrrrr_setup_topic_debuggingPs  zArchiver._setup_topic_debuggingc Cst|j|j|_t|}||jk}t|j||jd|j|_|j|O_| t || |t |ddrGt |ddrGt dd|_|jrTtddt|t |tspt dt d t d ttStrxt t|jrd dl}d dl}t d |jt |jd \}|!}t"t#}|$z-t||W|%|&|j'dr|(|j|n t)j*|j|ddWdS|%|&|j'dr|(|j|wt)j*|j|ddw1swYdSt||S)N)levelrrrFrz;Ignoring --stats. It is not supported when using --dry-run.rzborgbackup version %szYYou do not have a supported version of the msgpack python package installed. Terminating.zVThis should never happen as specific, supported versions are required by our setup.py.z-Do not contact borgbackup support about this.rzWriting execution profile to %sr5z.pyprofT)Z use_bin_type)+rErrrrr rrrrvarsr rrrrrrrrr rrVrr/r+rUPURE_PYTHON_MSGPACK_WARNINGrcProfilerrrZProfiler{localsenabledisableZsnapshot_statsendswithrFrmpack) rrrrr$rrpZprofiler variablesrrrrunXsZ                z Archiver.run)NNr)Wrrrrrrr staticmethodr rrr r5rNrrr;rCrGrLrr)rSrrrZREADrrVr>r:r{r}rrUrrrrrrrrrrrrrrrrrrrr3r4rr:rErHr\rerlrnrorrrsr}rr collections OrderedDictrrrrrr rrrrrTrrr r+rrrrrs     & &    P +9d   Y    0    V<     1 a J *  F    |   1  7 B            y:f~. + rc Cs:t|tjt|D]n}|d|dj}}|dvrN|d}z |d}|dj}Wn ty:d\}}Ynwt |dt |d t |n5|d vrz|d j }z|d}Wn tyjd}Ynwt |dt |d nq Wd d SWd d SWd d S1swYd S)zLsearch the stack for infos about the currently processed file and print themr)rrrrpr)rrror)r(rz/???N) rZsignalSIG_IGNinspectgetouterframesf_localstellst_sizerrrr>r)sig_nostackframerlocrposrrrrsig_info_handlers:   "   "r<cCs*tdtjddtjdtdS)Nz) Received SIGUSR2 at %s, dumping trace...r) microsecondr)rrnowrrr faulthandlerZdump_traceback)r7r8rrrsig_trace_handlers r@c Csttjjtjjdddt_ttjjtjjdddt_ttdt t tdt t rtdt t Ytdt Btdt+td t t}d}}}tj}z |tjtjd }Wnty}z6|}|jrytjntj}td t}t|tjd |tjkrt|tjd t|jWYd}~nLd}~wt j!y}ztt"|tjd tt#WYd}~n,d}~wt$yd }td t}t|tjd t|tjd tt#Ynwzt% |&|}Wdn 1swYWnty>}z&|}t'|j(}|jr$tjntj}td t}|j}WYd}~nd}~wt)j*y}z<|j+dvoO|j}|j+}|rYtjntj}|rc|j,}n|}d -dd|j.D}|d t7}t#}WYd}~nld}~wt$yd }d}tj}td t}t#}YnLt yd}tj}td t}t/d}Yn0t yd}d}tj}td t}t/d}Ynt yd}d}t/d}Ynw|rt0j1||d|rt02|||j3rUt4d} d} |t5kr| 6| d|fn9|t7kr+| 8| d|fn*|t#kr:| 1| d|fn|t/krI| 1| d |fn | 1| d!|pQd"ft|Wdn 1sewYWdn 1suwYWdn 1swYWdn 1swYWdn1swYWddSWddS1swYdS)#NrT)line_bufferingSIGINTSIGHUPSIGTERMSIGUSR1SIGUSR2ZSIGINFOZSSH_ORIGINAL_COMMANDrrzLocal Exception)Z LockTimeoutcss|]}d|VqdS)z Borg server: Nr)rlrrrrszmain..rzKeyboard interruptrzReceived SIGTERMzSignal.SIGTERMzReceived SIGHUP.z Signal.SIGHUPr)rrz!terminating with %s status, rc %dsuccessrrr0Zabnormali)9r^rrrencodingrr?r&rZr[rr\r]r<r@rrERRORrrrEr{rr-Z get_message tracebackr format_excrXrexitrrrrr+rrnr+rrrZRPCErrorZexception_classZexception_fullrarr,rrlogrrr)rr*r) archiverrrtbZ tb_log_levelrrrZ importantZ rc_loggerZexit_msgrrrmains                  TrR__main__) FFFTFTFTN)rrLrr-r/r?rr2rrrrErrrhr0rrr9rrbinasciirr contextlibrrrr rrr r rrFr r Zalgorithms.checksumsr rrrrrrrrrrrrrrrrrrrr constantscompressr!rWr"r#r$r%r&r'Zcrypto.keymanagerr(r)r*r+r,r-r.r/r0r1r2r3r4r5r6r7r8r9r:r;r<r=r>r?r@rArBrCrDrErFrGrHrIrJrKrLrMrNrOrPrQrRrSrTrUrVrWrXrYrZr[r\r]r^r_r`rarbrcrdrerfrgrhrirjrkrlrmrnrorprqZhelpers.parseformatrrrsZnanorstrtrrurvrwrxryrrzr{r!r|r}r~rrZremoterrrrrrrrrrZupgraderrr BaseException print_excrNrr#r9r,rTarFileZextraction_filterrrrrrZActionrrr<r@rRrrrrrs$                          K N k