libtrash.conf(5)

NAME
libtrash.conf - User configuration file template for libtrash.

SYNOPSIS
libtrash.conf is a user configuration file providing options that control the preloaded libtrash.so library. It is placed in the user home directory called .libtrash .

DESCRIPTION
The libtrash.conf file serves two purposes.
    1. As a source of compile-time directives and constants.
    2. As a user configuration to override defaults as to how the Trash can functionality performs.

OPTIONS
User Configuration
    This setting controls the interception of calls to unlink(). If it is set to NO, the "real" unlink() (the one found in GNU libc) will be used and data will be lost; if it set to YES, calls to unlink() will be intercepted and the "deleted" files will be stored in your trash can: INTERCEPT_UNLINK = YES This setting controls the interception of calls to rename(). If it is set to NO, the "real" rename() (the one found in GNU libc) will be used and data might be lost; if it set to YES, calls to rename() will be intercepted and, if any file is overwritten, it will be stored in your trash can: INTERCEPT_RENAME = YES This setting controls the interception of calls to fopen(). If it is set to NO, the "real" fopen() (the one found in GNU libc) will be used and data might be lost; if it set to YES, calls to fopen() will be intercepted and any truncated files will be stored in your trash can: INTERCEPT_FOPEN = YES This setting controls the interception of calls to freopen(). If it is set to NO, the "real" freopen() (the one found in GNU libc) will be used and data might be lost; if it set to YES, calls to freopen() will be intercepted and any truncated files will be stored in your trash can: INTERCEPT_FREOPEN = YES This setting controls the interception of calls to open(). If it is set to NO, the "real" open() (the one found in GNU libc) will be used and data might be lost; if it set to YES, calls to open() will be intercepted and any truncated files will be stored in your trash can: INTERCEPT_OPEN = YES This setting sets the default name of the directory in the user's home directory in which "deleted" files will be stored. It mustn't contain any slashes: TRASH_CAN = Trash This setting defines what should be done in case of failure: should we just call the desired function in GNU libc's using the argument we were passed or do nothing at all? (Note: There is one possible error situation in which we wouldn't even be able to invoke glibc's functions(): if the corresponding call to dlsym() had failed. The other possible errors are caused either by allocation failures, the impossibility to determine information about the user or by the fact that we were unable to create a file/directory. In any of these cases, we can always just pass our argument to the "real" function, if that is what the user prefers.) Please set it to either ALLOW_DESTRUCTION (to use the "real" GNU libc function, without the protection of libtrash) or PROTECT (to return an error code without invoking the appropriate function, making sure that even if an error occurs, that file won't be lost): IN_CASE_OF_FAILURE = PROTECT This setting defines whether, when libtrash is disabled (i.e., when the environment variable TRASH_OFF is set), the user gets warned about that fact whenever one of the overriden functions is invoked. Set to either YES or NO: SHOULD_WARN = NO This setting defines what we will do if asked to destroy a file under the user's TRASH_CAN. There is one thing we must refuse to do: handle it normally (i.e., storing a copy of it under TRASH_CAN/TRASH_CAN/). The file would never be deleted and you would get a chain of TRASH_CAN directories under your TRASH_CAN. So we can either protect the trash can (by setting this variable to YES), or allow direct destruction of files already inside it (by variable it to NO). Please note that, if you set this setting to NO, you will _NOT_ be fully protected from devastating commands such as In this case, libtrash would store a copy of all "deleted" files under your TRASH_CAN, but would still allow the removal of all of them from your TRASH_CAN. (Depending on the order in which rm deletes files under your home dir, the consequences might vary: if it only tried to unlink() the files under TRASH_CAN _after_ having "deleted" all the others, you would lose everything; if, on the other hand, it first unlink()ed the files under TRASH_CAN and then proceeded to the others, you would just lose the files you had originally stored under TRASH_CAN itself). In other words, you probably want to set it to YES, and just set it to NO in the environment when you need to forcefully remove files under your TRASH_CAN: PROTECT_TRASH = YES This setting defines a semi-colon delimited list of file name extensions (i.e., file types) which should be "ignored": files with matching file names won't be copied into your trash can before being destroyed. To disable this feature, leave t. Note: You must NOT precede each extension with a dot; e.g., to ignore C source and header files, this setting should be set to c;h NOT .c;.h IGNORE_EXTENSIONS = o;log;aux This setting defines whether hidden files (or files under a hidden directory) should be handled normally or "ignored". Usually, hidden files are either temporary or configuration files. Set to either YES or NO. YES tells libtrash to "ignore" such files, i.e., to allow their permanent destruction. Choosing NO causes them to be handled "normally", i.e., they will be moved to your trash can rather than really destroyed: IGNORE_HIDDEN = YES This setting defines whether files whose names end in a tilde ('~') should be handled normally or really "ignored". Usually, these files are backup files used by text editors. Set to either YES or NO. YES tells libtrash to "ignore" such files, i.e., to allow their permanent destruction. Choosing NO causes them to be handled "normally", i.e., they will be moved to your trash can rather than really destroyed: IGNORE_EDITOR_BACKUP = YES This setting defines whether files whose names begin with a cardinal ('#') should be handled normally or "really" ignored. Usually, these files are temporary files used by text editors. Set to either YES or NO. YES tells libtrash to "ignore" such files, i.e., to allow their permanent destruction. Choosing NO causes them to be handled "normally", i.e., they will be moved to your trash can rather than really destroyed: IGNORE_EDITOR_TEMPORARY = YES This setting allows you to instruct libtrash to never allow the destruction of your personal libtrash configuration file. The idea behind this variable is the following: if you accidentally issue a command which makes your personal libtrash configuration file "disappear", libtrash won't behave in the way you would expect it to behave, and you might not notice that until it is too late. This would be particularly serious if your variables differ from the compile-time defaults in important aspects. If you consider this additional protection useful, set this setting to YES; otherwise, choose NO (your libtrash configuration file will, in this case, be handled according to the other rules): LIBTRASH_CONFIG_FILE_UNREMOVABLE = YES This setting determines whether requests by users which would cause the destruction of a file outside of their home directory are intercepted, i.e., if such files are moved to the user's trash can or really destroyed. Of course, any of these things will only happen if the user has sufficient permissions. If you set this variable to YES, you should take a look at TRASH_SYSTEM_ROOT below. An example: Alice tries to unlink() / common / latest-news.txt. If you set GLOBAL_PROTECTION to YES, / common / latest-news.txt will be moved to / home / alice / Trash / SYSTEM_ROOT / common / latest-news.txt, assuming that TRASH_SYSTEM_ROOT is set to SYSTEM_ROOT. If GLOBAL_PROTECTION had the value NO, / common / latest-news.txt would be unlink()ed using glibc's unlink(), and no copy would be stored in Alice's TRASH_CAN. If Alice lacked write-permission to that directory in the first place, her request would naturally fail. NOTES: 1- This _DOESN'T_ apply to requests which would destroy files under one of the "protected" directories listed in UNREMOVABLE_DIRS: if the super user lists /lib in unremovable_dirs, and sets GLOBAL_PROTECTION, trying to unlink(), e.g., /lib/libc.so.6 will still fail: the original file (actually, it is a symlink) will be left in the same place, and it won't be copied to her TRASH_CAN. If GLOBAL_PROTECTION hadn't been set, exactly the same thing would have happened: this request would have been ignored. Summary: UNREMOVABLE_DIRS takes precedence over GLOBAL_PROTECTION. 2- Files under TEMPORARY_DIRS are always ignored: e.g., requests to unlink() files under these dirs are passed on to glibc's unlink() independently of the value of GLOBAL_PROTECTION. It doesn't make any sense to allow storing back-up copies of temporary files; besides, this would make your TRASH_CAN unbrowsable due to the quantity of litter (pun intended). 3- If you set GLOBAL_PROTECTION to YES, and then proceed to delete a file on a partition or file system different from the one on which your home directory resides, the file will be _copied_ byte-after-byte to your trash can. If the file is very large (e.g., ISO images), that operation will take some time. GLOBAL_PROTECTION = YES This setting sets the default name of the directory under TRASH_CAN which will serve as "root" of the file system if you have set GLOBAL_PROTECTION above (if GLOBAL_PROTECTION is set to NO, this value is ignored). E.g.: if you set this setting to SYSTEM_ROOT, and GLOBAL_PROTECTION is set to YES, trying to unlink() /common/interesting-stuff/important.html will result in a copy of the deleted file in / (YOUR_HOME_DIR) / (YOUR_TRASH_CAN) / SYSTEM_ROOT / common / interesting-stuff / important.html. Just like TRASH_CAN, it musn't contain any slashes - it should be a plain directory name: TRASH_SYSTEM_ROOT = SYSTEM_ROOT This variable defines a list of directories under which no files will ever be destroyed by the user running a program under libtrash. They won't be transferred to the user's TRASH_CAN: these requests are simply ignored and an error code is returned after each call to the "wrapped" functions. NOTES: 1- Each user can choose her own list of "untouchable" dirs. 2- root can use this variable to prevent catastrophic events which would render a system unusable, e.g., "rm -r /". Leave this setting empty (i.e., enter a newline after the equal sign) if you don't need this feature. Otherwise, fill in a semi-colon separated list of directories. A list of system directories which will prevent root from seriously damaging the system is provided as an alternative. 3- Directories can be easily removed from this list at run-time through the use of the UNCOVER_DIRS environment variable (see below). UNREMOVABLE_DIRS=/bin;/boot;/dev;/etc;/lib;/lib64;/opt;/sbin;/usr This is a convenience configuration variable: it simply instructs libtrash to temporarily remove the listed directory(ies) from the UNREMOVABLE_DIRS variable. Additionally, it can also be used to override PROTECT_TRASH from the command line, so that you can permanently destroy files in your trash can without having to completely disable libtrash during that interval. I came up with this idea when I noticed that, more often than not, whenever I issued a command as root I was prefixing it with either "TRASH_OFF=YES" or "UNREMOVABLE_DIRS=''", because it would typically try either to perform changes in one of the UNREMOVABLE_DIRS or to permanently remove files from my trash can. For that reason, you can now easily remove the directory(ies) you are updating from UNREMOVABLE_DIRS without completely disabling libtrash. Notes: 1- Since this variable lists exceptions to UNREMOVABLE_DIRS, it is empty by default and can't be set in the personal configuration file: it is meant to be used only at the command line (e.g., "UNCOVER_DIRS=/usr/ rm /usr/foo"). 2- You can set UNCOVER_DIRS to one or more subdirectories of a (higher level) directory listed in UNREMOVABLE_DIRS. This means that if you have set UNREMOVABLE_DIRS to /abc, and wish to delete everything beneath /abc/def/, you can use the command "UNCOVER_DIRS=/abc/def rm -R /abc/def" -- you only need to "uncover" what you wish to destroy or modify. 3- The format is the same as for UNREMOVABLE_DIRS: semi-colon separated list of directories, without any white-space in the middle and without quotes. To override PROTECT_TRASH, just list the path to your trash can. 4- AGAIN: (i) Leave UNCOVER_DIRS empty in this file. (ii) Don't set UNCOVER_DIRS in your personal configuration file. ==> (iii) Use it only as an environment variable. UNCOVER_DIRS = This setting sets a list of directories under which temporary files are created. We always destroy files under any of these directories. This must be a semi-colon separated list of directories. Leave this setting empty (i.e., enter a newline after the equal sign) if you don't need/want this exception: TEMPORARY_DIRS = /run;/tmp;/var This setting defines a list of directories inside each user's home directory under which temporary files are created. We always destroy files under any of these directories. This must be a semi-colon separated list of directory names *relative to the users' home dirs*, and with no leading or trailing slashes. Leave this setting empty (i.e., enter a newline after the equal sign) if you don't need/want this exception. Example: setting USER_TEMPORARY_DIRS = temp will lead to the permanent destruction of deleted files beneath /root/temp, /home/user1/temp, /home/user2/temp, etc..., which might be useful if some program creates temporary files in /{$HOME}/temp whenever it is run. USER_TEMPORARY_DIRS = This setting sets a list of directories under which files are really destroyed, exactly like what happens in the directories listed in TEMPORARY_DIRS. The only difference is that this variable is meant to be used to prevent files on removable media (e.g., floppies, CD-RW, etc) from having a copy of themselves "saved" in your trash can if GLOBAL_PROTECTION is set. It is enabled by default, since I suppose that for most people saving back-up copies of files destroyed on a removable medium doesn't make a lot of sense. For that reason, and to prevent those unnecessary copies from being made, fill in a semi-colon separated list of directories which are used as mount points for removable media in your system. If you wish to have that extra level of protection enabled, just leave this variable unset (i.e., enter a newline after the equal sign) - and don't forget to enable GLOBAL_PROTECTION, of course): NOTE: This variable is ignored if global_protection is disabled. REMOVABLE_MEDIA_MOUNT_POINTS = /cdrom;/media;/mnt This setting is meant to allow certain programs to function correctly while libtrash is enabled. More specifically, it can be used to create a list of "exceptions": files which would normally be considered unremovable lose their protection if listed here. This is important because some programs might need to delete files in UNREMOVABLE_DIRS; e.g., the commands mount/umount need to create/delete a lock file in /etc, while it is usually a good idea to mark /etc as unremovable. You can also use this variable to make libtrash work from /etc/ld.so.preload without interfering with your boot/shutdown procedure. Notes: 1) Use a semi-colon separated list, no white-space between items. 2) Not only files with a path listed in EXCEPTIONS lose their protection; any file with a path *starting* with one of the paths listed here loses its protection (eg, both /usr/abcd and /usr/abc/d will lose their protection if /use/abc is listed here). This is a feature -- not a bug -- so that mount can delete any file with a name starting with /etc/mtab. EXCEPTIONS = /etc/mtab;/etc/resolv.conf;/etc/adjtime;/etc/upsstatus;/etc/dhcpc Files which match this regular expression will be ignored. WARNING: In the configuration file used at compile time all backslashes MUST be double, but in the personal configuration files they MUST NOT be double. (This is due to the fact that the C compiler interprets the backslash as an escape character.) IGNORE_RE = The following setting can only be defined at run-time in your personal libtrash configuration file. Setting it at compile-time will produce NO EFFECT. Files which are greater than PRESERVE_FILES_LARGER_THAN will always be left untouched If this value is set, then all operations that would delete a file larger than PRESERVE_FILES_LARGER_THAN will fail with an error. Value must be an integer immediately followed by M, m, G or g. This suffix is NOT optional. Example: PRESERVE_FILES_LARGER_THAN = 1G
        means trying to delete any file larger than 1 gigabyte will fail
    PRESERVE_FILES_LARGER_THAN = 500M
        means attempts to delete any file larger than 500 megabytes will fail
    If you enable this setting and wish to circumvent it, you can use TRASH_OFF=YES.
Compile time Configuration
    stderr or run silently. You should either leave it set to NO (to disable the messages) or change NO to YES (to have libtrash print these messages) if you suspect something isn't working as it should: DEBUG = NO This setting specifies the name (WITHOUT a leading slash) of the user-specific, personal configuration file: PERSONAL_CONF_FILE = .libtrash String printed to stderr if SHOULD_WARN (see below) is set to YES: WARNING_STRING = Remember that libtrash is disabled.