Comments (14)
I like how Syncthing does it:
http://docs.syncthing.net/users/syncthing.html
https://github.com/syncthing/syncthing/blob/master/etc/linux-systemd/user/syncthing.service
For example, 5 signals that the process is restarting due to an upgrade. This information can be useful to the process supervision system.
So, perhaps think about what we would want to do about different kinds of exits, give each one a code, and document it.
Another option is to group exits are different but that we think should be handled in the same way, and give them all the same exit codes. But I think this approach tries to read the user's mind too much and should be avoided.
The great thing about good exit codes is that you don't really have to parse them at all :)
On June 20, 2015 5:24:34 PM EDT, TW [email protected] wrote:
how shall we deal with return codes of borg?
currently it is:
0 == no error, normal termination
1 == some errorthis could be way more informative. :)
0 == no error, normal termination
1 == some error that hasn't been assigned a better rc yet
2 == SIGINTR (ctrl-c)
3 == SIGTERM (normal "kill")
4... == other separately identifiable conditionswhat I am asking myself: are there standard return codes for some stuff
or does everybody invent them individually?what rc do we use if some files could not get processed (not found,
permissions problems, ...), but the rest was ok?
Reply to this email directly or view it on GitHub:
#61
from borg.
@lfam thanks for pointing at syncthing docs, I added the 128+N rc for signals.
from borg.
If someone wants to help:
research how other backup commandline tools handle return codes and document it here (link it from here).
from borg.
This is how fbackup does:
(pdf) http://h20565.www2.hp.com/hpsc/doc/public/display?docId=emr_na-c02260774
RETURN VALUE
fbackup returns one of the following values:
0 upon normal completion.
1 if it is interrupted but allowed to save its state for possible restart.
2 if any error conditions prevent the session from completing.
4 if any warning conditions are encountered.
If warnings occur, the operator should check the fbackup logs to verify the sanity of the backup.
from borg.
rsnapshot: http://linux.die.net/man/1/rsnapshot
Exit Values
0 All operations completed successfully
1 A fatal error occurred
2 Some warnings occurred, but the backup still finished
from borg.
GNU tar: http://www.gnu.org/software/tar/manual/html_section/tar_19.html
Possible exit codes of GNU tar are summarized in the following table:
0
`Successful termination'.
1
`Some files differ'. If tar was invoked with `--compare' (`--diff',
`-d') command line option, this means that some files in the archive
differ from their disk counterparts (see section Comparing Archive
Members with the File System). If tar was given `--create', `--append'
or `--update' option, this exit code means that some files were changed
while being archived and so the resulting archive does not contain the
exact copy of the file set.
2
`Fatal error'. This means that some fatal, unrecoverable error
occurred.
If tar has invoked a subprocess and that subprocess exited with a
nonzero exit code, tar exits with that code as well. This can happen,
for example, if tar was given some compression option (see section
Creating and Reading Compressed Archives) and the external compressor
program failed. Another example is rmt failure during backup to the
remote device (see section Remote Tape Server).
That last paragraph is interesting...
from borg.
Duplicity: http://duplicity.nongnu.org/epydoc/duplicity.log.ErrorCode-class.html
Enumeration class to hold error code values. These values should never
change, as frontends rely upon them. Don't use 0 or negative numbers.
This code is returned by duplicity to indicate which error occurred via
both exit code and log.
generic = 1
command_line = 2
hostname_mismatch = 3
no_manifests = 4
mismatched_manifests = 5
unreadable_manifests = 6
cant_open_filelist = 7
bad_url = 8
bad_archive_dir = 9
bad_sign_key = 10
restore_dir_exists = 11
verify_dir_doesnt_exist = 12
backup_dir_doesnt_exist = 13
file_prefix_error = 14
globbing_error = 15
redundant_inclusion = 16
inc_without_sigs = 17
no_sigs = 18
restore_dir_not_found = 19
no_restore_files = 20
mismatched_hash = 21
unsigned_volume = 22
user_error = 23
boto_old_style = 24
boto_lib_too_old = 25
boto_calling_format = 26
ftp_ncftp_missing = 27
ftp_ncftp_too_old = 28
exception = 30
gpg_failed = 31
s3_bucket_not_style = 32
not_implemented = 33
get_freespace_failed = 34
not_enough_freespace = 35
get_ulimit_failed = 36
maxopen_too_low = 37
connection_failed = 38
restart_file_not_found = 39
gio_not_available = 40
source_dir_mismatch = 42
ftps_lftp_missing = 43
volume_wrong_size = 44
enryption_mismatch = 45
backend_error = 50
backend_permission_denied = 51
backend_not_found = 52
backend_no_space = 53
from borg.
rdiff-backup: http://www.nongnu.org/rdiff-backup/rdiff-backup.1.html
EXIT STATUS
If rdiff-backup finishes successfully, the exit status will be 0. If
there is an unrecoverable (critical) error, it will be non-zero (usu-
ally 1, but don't depend on this specific value). When setting up
rdiff-backup to run automatically (as from cron(8) or similar) it is
probably a good idea to check the exit code.
rdiff-backup also has an error policy, which I think is a good approach for backup software: http://www.nongnu.org/rdiff-backup/error_policy.html
from borg.
bsdtar
FreeBSD: https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1
EXIT STATUS
The tar utility exits 0 on success, and >0 if an error occurs.
OpenBSD: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/tar.1?query=tar&sec=1
EXIT STATUS
The tar utility exits with one of the following values:
0
All files were processed successfully.
1
An error occurred.
from borg.
It seems that even a return value of 1 is not defined consistently, since for GNU tar it does not mean "otherwise undefined fatal error".
I like Duplicity's approach. It provides a rich interface for shell scripting that does NOT involve parsing strings. Sure, it could get messy (okay, it probably already has... what is 'user_error'?), but it's nice to treat 'backend_no_space' differently from 'connection_failed'.
from borg.
if we are going to go Duplicity's way, it seems the proper way would be to have a library of Python exceptions with each its own unique integer identifier, and fire those as relevant.
but it seems a little cracked up: i think returning 1 on errors, 0 on success would be sufficient, provided the error message is meaningful. although 128+N is seems useful for splitting between external and internal error conditions...
from borg.
Maybe the smallest change that would make most people happy would be something like:
0 = complete success, no errors/warnings
1 = backup process reached its normal end, but there were some errors/warnings (this usually means most stuff was backed up, but not everything)
2 = backup process either did not start or it ended abnormally and did not reach its normal end, there was some fatal error (this usually means either nothing was backed up or the backup is very incomplete)
from borg.
would be fine with me. basically the same distinction as in #57 then...
from borg.
working on this.
from borg.
Related Issues (20)
- borg 1.4: drop buster-based binary? HOT 1
- locking related KeyError exception on every command HOT 8
- macOS passcommand syntax issue (base64 command) HOT 5
- 'borg create' stops when encountering invalid characters in filenames HOT 3
- cache_sync parse error: Unexpected object: integer HOT 6
- openindiana: non-existing runtime dir HOT 2
- [Question] Fixable data integrity errors? HOT 7
- Canonical path: resolve symbolic links? HOT 2
- Data integrity error: Segment entry data short read [segment 2, offset 36478608]: expected 676, got 359 bytes HOT 1
- Static binary for OpenBSD/NetBSD missing HOT 3
- Move path within repo HOT 2
- [1.2.7] borg check -repair lacks a summarizing information at the end when it actually repaired something(s)
- "compromised client" threat model HOT 1
- Backup to Hetzner Storage Share no longer working HOT 1
- moin 1.4: borg install docs, cygwin section refer to py38
- borg2: Creating archive fails at specific archive name HOT 3
- disk is full: `_get_default_tempdir` raises `FileNotFoundError` No usable temporary directory found in ['/tmp', '/var/tmp', '/usr/tmp', '/home/kmille'] HOT 7
- run in venv w/ root rights HOT 3
- As of 1.2.0, the ssh relative path hack "/./" works for most actions but not "borg init" HOT 4
- Please add a way to keep backups independently of pruning retention policy HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from borg.