bsparse

title: bsparse(8)

text:
# bsparse(8)

## NAME
bsparse - program for regenerating burp protocol2 sparse files

## SYNOPSIS
bsparse [OPTIONS] [PATH_TO_DEDUP_GROUP]

A program for regenerating burp protocol2 sparse files.

## OPTIONS
-c path

Path to config file (default: /etc/burp/burp.conf).

## EXAMPLES
bsparse -c /etc/burp/burp-server.conf /var/spool/burp/global

Regenerates the sparse index for the dedup_group 'global', using the client storage directories under /var/spool/burp/global/clients.

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.


burp

package: burp

title: burp(8)

summary: BackUp and Restore Program

text:
# burp(8)

## NAME
Burp - BackUp and Restore Program

## SYNOPSIS
burp [OPTIONS]

## DESCRIPTION
BackUp and Restore Program.

## SERVER OPTIONS
-a c

Run as a stand-alone champion chooser process (useful for debugging protocol2 style backups).

-c [path]

Short for 'config file'. The argument is a path to the config file. The default is /etc/burp/burp.conf.

-F

Foreground mode. The server will fork into the background and run as a daemon if you do not give this option.

-g

Generate initial CA keys and certificates, and then exit.

-h

Print help and then exit.

-?

Print help and then exit.

-i

Print an index table of symbols that humans may see burp produce, and exit.

-n

No forking mode. The program will accept a single query, deal with it, and then exit. This is useful for debugging. Implies '-F'. If you intend to debug a protocol2 session, you will also want to run a separate champion chooser process ('-a c' below).

-o [option=value]

Override a given option. You can use this flag several times to override multiple options. You can even reset list options with the special syntax ':=' (example: '-o "include:=/tmp"').

-Q

Do not log to stdout (overrides config file 'stdout' setting).

-t

Dry-run mode to test config file syntax.

-v

Log to stdout (overrides config file 'stdout' setting).

-V

Print version and exit.

ADDITIONAL SERVER OPTIONS TO USE WITH '-a c'

-C [client]

Run as if forked via a connection from this client.

## CLIENT OPTIONS
-a [b|t|r|R|l|L|p|v|V|delete|e|T|d|D]

Short for 'action'. The arguments mean backup, timed backup, restore, Restore, list, long list, parseable list, verify, Verify, delete, estimate, timer check, diff, or long diff, respectively.

-b [number|a]

Short for 'backup number'. The argument is a number, or 'a' to select all backups.

-c [path]

Short for 'config file'. The argument is a path to the config file. The default is /etc/burp/burp.conf, or %PROGRAMFILES%\Burp\burp.conf on Windows.

-C [client]

Allows you to specify an alternative client to list or restore from. Requires that the server configuration of the alternative client permits your client to do this. See the 'restore_client' and 'super_client' options.

-d [path]

Short for 'directory'. When restoring, the argument is a path to an alternative directory to restore to. When listing, the argument is the directory to list.

-f

Short for 'force overwrite'. Without this option set, a restore will not overwrite existing files.

-h

Print help and then exit.

-?

Print help and then exit.

-o [option=value]

Override a given option. You can use this flag several times to override multiple options. You can even reset list options with the special syntax ':=' (example: '-o "include:=/tmp"').

-i

Print an index table of symbols that humans may see burp produce, and exit.

-q [max secs]

When running a timed backup, sleep for a random number of seconds (between 0 and the number given) before contacting the server. Alternatively, this can be specified by the 'randomise' configuration file option.

-Q

Do not log to stdout (overrides config file 'stdout' setting).

-r [regex]

Short for 'regular expression'. The argument is a case sensitive regular expression with which to match backup files. Use it for lists, restores and verifies.

-R [regex]

Case insensitive alternative to '-r'.

-s [number]

For use with restores - strip a number of leading path components.

-t

Dry-run mode to test config file syntax.

-v

Log to stdout (overrides config file 'stdout' setting).

-x

On restore, do not use the Windows VSS API, and strip out the VSS data. Works both on Windows and non-Windows.

-X (Windows only)

On restore, do not use the Windows VSS API and do not attempt to strip out the VSS data. Give this option when you are restoring a backup that contains no VSS data.

-a s

Run this to connect to a running server to get a live monitor of the status of all your backup clients. The live monitor requires ncurses support at compile time.

-a S

Similar to '-a s', but it prints the main status monitor summary screen to stdout. One application is that a script can run this and email an administrator the output on a cron job. This doesn't require ncurses support. There are additional options that can be given with both these options, listed below.

ADDITIONAL CLIENT OPTIONS TO USE WITH '-a s' and '-a S'

-C [client]

Limit the output to a single client.

-b [number]

Show listable files in a particular backup (requires -C).

-z [file]

Dump a particular log file in a backup (requires -C and -b).

-d [path]

Show a particular path in a backup (requires -C and -b).

-l [path]

Log file for status monitor - useful for debugging.

ADDITIONAL CLIENT OPTIONS TO USE WITH '-a b'

-o seed_src=<directory> -o seed_dst=<directory>

Make a seeding backup. The source directory is replaced with the destination directory on completion. Both paths need to be absolute. Your configured include paths need to be the same as the source directory, or within the source directory. There must be no other existing backups of the client running the seed job. A use case might be to make an initial backup of a local hard drive, and then to ship the hard drive to a remote location for subsequent backups.

## EXAMPLES
burp -a b

Runs a backup.

burp -a t

Timed backup. The same as 'burp -a b', except that a script is run on the server before deciding to go ahead. The intention is that this command will be run on a repeating cron job with a short interval, and that the server will decide when it is time for a new backup.

burp -a l

Lists the available backups and dates.

burp -a l -b 1

Lists all the files in backup number 1.

burp -a l -b a

Lists all the files in all the backups.

burp -a l -b c

Lists all the files in the current backup.

burp -a l -b 1 -r myregex

Lists all the files in backup number 1 that match the regular expression 'myregex'.

burp -a L -b 1 -r myregex

Long lists all the files in backup number 1 that match the regular expression 'myregex'. This is like doing an 'ls -l'.

burp -a L -b 1 -d ''

Long list the top level directory of backup 1.

burp -a L -b 1 -d '/home/graham'

Long list the /home/graham directory of backup 1. These '-d' versions of the list function provide the ability to 'browse' backups.

burp -C altclient -a L

Long list the top level directory of backup 1 of client 'altclient'.

burp -a r -d /tmp/restoredir

Restores all the files in the most recent backup into the directory /tmp/restoredir.

burp -a r -b 1 -d /tmp/restoredir -r myregex

Restores all the files in backup number 1 into the directory /tmp/restoredir, if they match the regular expression 'myregex'.

burp -a r -b 1 -d /tmp/restoredir -r myregex -s 2

Restores all the files in backup number 1 into the directory /tmp/restore, if they match the regular expression 'myregex', and strip 2 leading path components.

burp -C altclient -a r -b 1 -d /tmp/restoredir -r myregex

Restores all the files in backup number 1 of client 'altclient' into the directory /tmp/restoredir, if that match the regular expression 'myregex'.

burp -a v

Verifies the most recent backup.

burp -a v -b 1 -r myregex

Verifies everything in backup number 1 that matches the regular expression 'myregex'.

burp -a delete -b 1

Deletes backup number 1. Note that burp will not delete backup directories that other backup directories depend upon.

burp -a d -b 1 -b 2

Report the differences between backups 1 and 2 (use -a D for more verbosity).

burp -a p -b 1

Lists all the files in backup number 1, in burp-parsable list format. You may append something like '>/tmp/restore_list' to send to a file, edit, then use as an input for restoring. As in the following command:

burp -a r -b 1 -o restore_list=/tmp/restore_list

Restores from backup 7, matching the list of files given in /tmp/restore_list. The files given must be ordered as they would be in the output of a burp list command.

burp -a p -b 6 | burp -a R -b 7

Restores from backup 7, matching the list of files on standard input, which is provided by burp's list of backup 6 ('-a R' is shorthand for '-a r -o restore_list=-').

burp -a p -b 6 | burp -a V -b 7

Verifies from backup 7, matching the list of files on standard input, which is provided by burp's list of backup 6 ('-a V' is shorthand for '-a v -o restore_list=-').

burp -a s

Run the ncurses status monitor.

burp -a S

Print a status monitor snapshot, summarising all clients.

burp -C testclient -a S

Print a status monitor snapshot, showing client 'testclient' only.

## SERVER CONFIGURATION FILE OPTIONS
. [glob]

Read additional configuration files.

mode=server

Required to run in server mode.

listen=[address]:[port]

Defines the main TCP address and port that the server listens on. Specify multiple 'listen' entries on separate lines in order to listen on multiple addresses and ports. Each pair can be configured with its own 'max_children' value.

listen_status=[address]:[port]

Defines the main TCP address and port that the server listens on for status requests. Specify multiple 'listen_status' entries on separate lines in order to listen on multiple addresses and ports. Each pair can be configured with its own 'max_status_children' value. Comment out to have no status server.

network_allow=[string]

Allows access for the specified network or address. For example: '::1' or '127.0.0.1/8'. Specify multiple 'network_allow' entries on separate lines to allow multiple networks or addresses. If this option is not given, all networks are allowed. This option can be overridden by the client configuration files in clientconfdir on the server.

network_allow_status=[string]

Allows access for the specified network or address to the status server. For example: '::1' or '127.0.0.1/8'. Specify multiple 'network_allow' entries on separate lines to allow multiple networks or addresses. If this option is not given, all networks are allowed. This option can be overridden by the client configuration files in clientconfdir on the server.

cname_lowercase=[0|1]

Whether to force lowercase cname when looking-up in clientconfdir. This also affects the fqdn lookup on the client (see client configuration options for details). The default is 0. When set to 1 the name provided by the client while authenticating will be lowercased.

cname_fqdn=[0|1]

Whether to keep fqdn cname (like 'testclient.example.com') when looking-up in clientconfdir. This also affects the fqdn lookup on the client (see client configuration options for details). The default is 1. When set to 0, the fqdn provided by the client while authenticating will be stripped ('testclient.example.com' becomes 'testclient').

daemon=[0|1]

Whether to daemonise. The default is 1.

fork=[0|1]

Whether to fork children. The default is 1.

directory=[path]

Path to the directory in which to store backups.

directory_tree=[0|1]

When turned on (which is the default) and the client is on version 1.3.6 or greater, the structure of the storage directory will mimic that of the original filesystem on the client.

timestamp_format=[strftime format]

This allows you to tweak the format of the timestamps of individual backups. See 'man strftime' to see available substitutions. If this option is unset, burp uses "%Y-%m-%d %H:%M:%S %z".

password_check=[0|1]

Allows you to turn client password checking on or off. The default is on. SSL certificates will still be checked if you turn passwords off. This option can be overridden by the client configuration files in clientconfdir on the server.

clientconfdir=[path]

Path to the directory that contains client configuration files.

protocol=[0|1|2]

Choose which style of backups and restores to use. 0 (the default) automatically decides based on the client version and which protocol is set on the client side. 1 forces protocol1 style (file level granularity with a pseudo mirrored storage on the server and optional rsync). 2 forces protocol2 style (inline deduplication with variable length blocks). If you choose a forced setting, it will be an error if the client also chooses a forced setting. This option can be overridden by the client configuration files in clientconfdir on the server.

lockfile=[path]

Path to the lockfile that ensures that two server processes cannot run simultaneously.

pidfile=[path]

Synonym for lockfile.

syslog=[0|1]

Log to syslog. Defaults to off.

stdout=[0|1]

Log to stdout. Defaults to on.

keep=[number]

Number of backups to keep. This can be overridden by the clientconfdir configuration files in clientconfdir on the server. Specify multiple 'keep' entries on separate lines in order to keep multiple periods of backups. For example, assuming that you are doing a backup a day, keep=7 keep=4 keep=6 (on separate lines) will keep 7 daily backups, 4 weekly backups (7x4=28), and 6 multiples of 4 weeks (7x4x6=168) - roughly 6 monthly backups. Effectively, you will be guaranteed to be able to restore up to 168 days ago, with the number of available backups exponentially decreasing as you go back in time to that point. In this example, every 7th backup will be hardlinked to allow burp to safely delete intermediate backups when necessary. You can have as many 'keep' lines as you like, as long as they don't exceed 52560000 when multiplied together. That is, a backup every minute for 100 years.

manual_delete=[path]

This can be overridden by the clientconfdir configuration files in clientconfdir on the server. When the server needs to delete old backups, or rubble left over from generating reverse patches with librsync=1, it will normally delete them in place. If you use the 'manual_delete' option, the files will be moved to the path specified for deletion at a later point. You will then need to configure a cron job, or similar, to delete the files yourself. Do not specify a path that is not on the same filesystem as the client storage directory.

hardlinked_archive=[0|1]

On the server, defines whether to keep hardlinked files in the backups, or whether to generate reverse deltas and delete the original files. Can be set to either 0 (off) or 1 (on). Disadvantage: More disk space will be used Advantage: Restores will be faster, and since no reverse deltas need to be generated, the time and effort the server needs at the end of a backup is reduced.

max_hardlinks=[number]

On the server, the number of times that a single file can be hardlinked. The bedup program also obeys this setting. The default is 10000.

librsync=[0|1]

When set to 0, delta differencing will not take place. That is, when a file changes, the server will request the whole new file. The default is 1. This option can be overridden by the client configuration files in clientconfdir on the server.

librsync_max_size=[B/KB/MB/GB]

Only use librsync when a file is less than the given size. Both the most recently backed up version of a file and the version to be backed up are checked. The default is 0, which means the option is off. This option can be overridden by the client configuration files in clientconfdir on the server.

compression=zlib[0-9] (or gzip[0-9])

Choose the level of zlib compression for files stored in backups. Setting 0 or zlib0 turns compression off. The default is zlib9. This option can be overridden by the client configuration files in clientconfdir on the server. 'gzip' is a synonym of 'zlib'. This option is applicable to protocol version 1 only.

hard_quota=[B/KB/MB/GB]

Do not back up the client if the estimated size of all files is greater than the specified size. Example: 'hard_quota = 100GB'. Set to 0 (the default) to have no limit.

soft_quota=[B/KB/MB/GB]

A warning will be issued when the estimated size of all files is greater than the specified size and smaller than hard_quota. Example: 'soft_quota = 95GB'. Set to 0 (the default) to have no warning.

version_warn=[0|1]

When this is on, which is the default, a warning will be issued when the client version does not match the server version. This option can be overridden by the client configuration files in clientconfdir on the server.

path_length_warn=[0|1]

When this is on, which is the default, a warning will be issued when the client sends a path that is too long to replicate in the storage area tree structure. The file will still be saved in a numbered file outside of the tree structure, regardless of the setting of this option. This option can be overridden by the client configuration files in clientconfdir on the server.

client_lockdir=[path]

Path to the directory in which to keep per-client lock files. By default, this is set to the path given by the 'directory' option.

user=[username]

Run as a particular user. This can be overridden by the client configuration files in clientconfdir on the server.

group=[groupname]

Run as a particular group. This can be overridden by the client configuration files in clientconfdir on the server.

readall=[0|1]

Keep readall capability when dropping root privileges (default 0). When enabled changes default atime to 1.

umask=[umask]

Set the file creation umask. Default is 0022.

ratelimit=[Mb/s]

Set the network send rate limit, in Mb/s. If this option is not given, burp will send data as fast as it can. If you want the server's sending speed to be limited, you will also need to set this option on the server side.

network_timeout=[s]

Set the network timeout in seconds. If no data is sent or received over a period of this length, burp will give up. The default is 7200 seconds (2 hours).

working_dir_recovery_method=[resume|delete]

This option tells the server what to do when it finds the working directory of an interrupted backup (perhaps somebody pulled the plug on the server, or something). This can be overridden by the client configurations files in clientconfdir on the server. Options are...

delete: Just delete the old working directory.

resume: Continue the previous backup from the point at which it left off. NOTE: If the client has changed its include/exclude configuration since the backup was interrupted, the recovery method will automatically switch to 'delete'. See also the 'resume attempts' option.

max_resume_attempts=[number]

If working_dir_recovery_method is 'resume', this option tells the server how many times to attempt to resume before giving up and deleting the working directory. The default is 0, which means to never give up.

client_can_delete=[0|1]

Turn this off to prevent clients from deleting backups with the '-a delete' option. The default is that clients can delete backups. Restore clients can override this setting.

client_can_diff=[0|1]

Turn this off to prevent clients from diffing backups with the '-a d' option. The default is that clients can diff backups. Restore clients can override this setting.

client_can_force_backup=[0|1]

Turn this off to prevent clients from forcing backups with the '-a b' option. Timed backups will still work. The default is that clients can force backups.

client_can_list=[0|1]

Turn this off to prevent clients from listing backups with the '-a l' option. The default is that clients can list backups. Restore clients can override this setting.

client_can_monitor=[0|1]

Turn this off to prevent clients from being able to run the status monitor. The default is that clients can run the status monitor. Restore clients can override this setting.

client_can_restore=[0|1]

Turn this off to prevent clients from initiating restores with the '-a r' option. The default is that clients can initiate restores. Restore clients can override this setting.

client_can_verify=[0|1]

Turn this off to prevent clients from initiating a verify job with the '-a v' option. The default is that clients can initiate a verify job. Restore clients can override this setting.

super_client=[client]

A client that is permitted to list, verify, restore, delete, and diff files belonging to any other client, according to the super_client's client_can permissions (eg, 'client_can_list'). You may specify multiple super_clients. If this is too permissive, you may set a super_client for individual original clients in the individual clientconfdir files, or look at the 'restore_client' option.

restore_client=[client]

A client that is permitted to list, verify, restore, delete, and diff files belonging to any other client, according to the client_can permissions on both the restore_client and the original_client (eg, 'client_can_list'). You may specify multiple restore_clients. If this is too permissive, you may set a restore_client for individual original clients in the individual clientconfdir files.

ssl_cert_ca=[path]

The path to the SSL CA certificate. This file will probably be the same on both the server and the client. The file should contain just the certificate in PEM format. For more information on this, and the other ssl_* options, please see docs/burp_ca.txt.

ssl_cert=[path]

The path to the server SSL certificate. It works for me when the file contains the concatenation of the certificate and private key in PEM format.

ssl_key=[path]

The path to the server SSL private key in PEM format.

ssl_key_password=[password]

Only needed for loading an encrypted certificate.

ssl_cert_password=[password]

Synonym for ssl_key_password.

ssl_ciphers=[cipher list]

Allowed SSL ciphers. See openssl ciphers for details.

ssl_compression=zlib[0|5] (or gzip[0|5])

Choose the level of zlib compression over SSL. Setting 0 or zlib0 turns SSL compression off. Setting non-zero gives zlib5 compression (it is not currently possible for openssl to set any other level). The default is 5. 'gzip' is a synonym of 'zlib'.

ssl_verify_peer_early=[0|1]

Verify and authenticate client certificates at SSL layer before receiving or sending Burp traffic. The default is to verify client certificates only after password authentication.

ssl_dhfile=[path]

Path to Diffie-Hellman parameter file. To generate one with openssl, use a command like this: openssl dhparam -dsaparam -out dhfile.pem 2048

max_parallel_backups=[number]

Defines the number of max parallel backups (the number of clients that are in a "working" state). The default is 0 - unlimited.

max_children=[number]

Defines the number of child processes to fork (the number of clients that can simultaneously connect. The default is 5. Specify multiple 'max_children' entries on separate lines if you have configured multiple 'listen' entries.

max_status_children=[number]

Defines the number of status child processes to fork (the number of status clients that can simultaneously connect. The default is 5. Specify multiple 'max_status_children' entries on separate lines if you have configured multiple 'listen_status' entries.

max_storage_subdirs=[number]

Defines the number of subdirectories in the data storage areas. The maximum number of subdirectories that ext3 allows is 32000. If you do not set this option, it defaults to 30000.

timer_script=[path]

Path to the script to run when a client connects with the timed backup option. If the script exits with code 0, a backup will run. The first three arguments are the client name, the path to the 'current' storage directory, and the path to the top level storage directories. The next two arguments are reserved, and user arguments (see timer_arg) are appended after that. An example timer script is provided. The timer_script option can be overridden by the client configuration files in clientconfdir on the server. If this option is not set, equivalent code internal to Burp will be run instead. The internal code also uses the timer_arg parameters.

timer_arg=[string]

A user-definable argument to the timer script. You can have many of these. The timer_arg options can be overridden by the client configuration files in clientconfdir on the server.

timer_repeat_interval=[m]

During a timed backup, the timer script can be run at regular intervals. If the client is out of timeband, the backup will be interrupted. For example, setting 5 will cause burp to check every five minutes. The default is 0, which means that the script will only run once at the start of the backup.

notify_success_script=[path]

Path to the script to run when a backup succeeds. User arguments are appended after the first six reserved arguments. An example notify script is provided. The notify_success_script option can be overriddden by the client configuration files in clientconfdir on the server.

notify_success_arg=[string]

A user-definable argument to the notify success script. You can have many of these. The notify_success_arg options can be overriddden by the client configuration files in clientconfdir on the server.

notify_success_warnings_only=[0|1]

Set to 1 to send success notifications when there were warnings. If this and notify_success_changes_only are not turned on, success notifications are always sent.

notify_success_changes_only=[0|1]

Set to 1 to send success notifications when there were new or changed files. If this and notify_success_warnings_only are not turned on, success notifications are always sent.

notify_failure_script=[path]

The same as notify_success_script, but for backups that failed.

notify_failure_arg=[string]

The same as notify_success_arg, but for backups that failed.

notify_failure_on_backup_with_failovers_left=[0|1]

In the case where there are server_failover entries left to try, you may not wish to notify on backup failure. The default is on.

notify_failure_on_backup_working_dir_deletion=[0|1]

On the next backup attempt after a backup was interrupted, it may not be possible to resume the previous backup. In this case (or if working_dir_recovery_method is 'delete'), the previous backup will be deleted. You may wish to be notified about this. The default is off.

dedup_group=[string]

Enables you to group clients together for file deduplication purposes. For example, you might want to set 'dedup_group=xp' for each Windows XP client, and then run the bedup program on a cron job every other day with the option '-g xp'.

server_script_pre=[path]

Path to a script to run on the server after each successfully authenticated connection but before any work is carried out. The arguments to it are 'pre', '(client command)', '(client name)', '(0 or 1 for success or failure)', '(timer script exit code)', and then arguments defined by server_script_pre_arg. If the script returns non-zero, the task asked for by the client will not be run. This command and related options can be overriddden by the client configuration files in clientconfdir on the server.

server_script_pre_arg=[string]

A user-definable argument to the server pre script. You can have many of these.

server_script_pre_notify=[0|1]

Turn on to send a notification email when the server pre script returns non-zero. The output of the script will be included in the email. The default is off. Most people will not want this turned on because clients usually contact the server at 20 minute intervals and this could cause a lot of emails to be generated. Requires the notify_failure options to be set.

server_script_post=[path]

Path to a script to run on the server before the client disconnects. The arguments to it are 'post', '(client command)', '(client name), '(0 or 1 for success or failure)', '(timer script exit code)', and then arguments defined by server_script_post_arg. This command and related options can be overriddden by the client configuration files in clientconfdir on the server.

server_script_post_arg=[string]

A user-definable argument to the server post script. You can have many of these.

server_script_post_notify=[0|1]

Turn on to send a notification email when the server post script returns non-zero. The output of the script will be included in the email. The default is off. Requires the notify_failure options to be set.

server_script=[path]

You can use this to save space in your config file when you want to run the same server script twice. It overrides server_script_pre and server_script_post. This command and related options can be overriddden by the client configuration files in clientconfdir on the server.

server_script_arg=[path]

Goes with server_script and overrides server_script_pre_arg and server_script_post_arg.

server_script_notify=[0|1]

Turn on to send notifications email when the server pre and post scripts return non-zero. The output of the script will be included in the email. The default is off. Requires the notify_failure options to be set.

server_script_post_run_on_fail=[0|1]

If this is set to 1, server_script_post will always be run. The default is 0, which means that if the task asked for by the client fails, server_script_post will not be run.

autoupgrade_dir=[path]

Path to autoupgrade directory from which upgrades are downloaded. The option can be left unset in order not to autoupgrade clients. Please see docs/autoupgrade.txt in the source package for more help with this option.

ca_conf=[path]

Path to certificate authority configuration file. The CA configuration file will usually be /etc/burp/CA.cnf. The CA directory indicated by CA.cnf will usually be /etc/burp/CA. If ca_conf is set and the CA directory does not exist, the server will create, populate it, and the paths indicated by ssl_cert_ca, ssl_cert, ssl_key and ssl_dhfile will be overwritten. For more detailed information on this and the other ca_* options, please see docs/burp_ca.txt.

ca_name=[name]

Name of the CA that the server will generate when using the ca_conf option.

ca_server_name=[name]

The name that the server will put into its own SSL certificates when using the ca_conf option.

ca_burp_ca=[path]

Path to the burp_ca script when using the ca_conf option.

ca_crl=[path]

Override the default path to the certificate revocation list.

ca_crl_check=[0|1]

Whether to check for revoked certificates in the certificate revocation list.

monitor_browse_cache=[0|1]

Whether or not the server should cache the directory tree when a monitor client is browsing. Advantage: browsing is faster. Disadvantage: more memory is used.

label=[string]

You can have multiple labels, and they can be overridden in the client configuration files in clientconfdir on the server. They will appear as an array of strings in the server status monitor JSON output. The idea is to provide a mechanism for arbirtrary values to be passed to clients of the server status monitor.

enabled=[0|1]

Set this to 0 if you want to disable all clients. The default is 1. This option can be overridden per-client in the client configuration files in clientconfdir on the server.

rblk_memory_max=[B/KB/MB/GB]

The maximum amount of data from the disk cached in server memory during a protocol2 restore/verify. The default is 256MB. This option can be overridden per-client in the client configuration files in clientconfdir on the server.

sparse_size_max=[B/KB/MB/GB]

The maximum (uncompressed) size of the sparse file of each protocol 2 dedup_group. The default is 256MB. If the sparse file grows beyond this size, entries will be removed starting with the oldest, unless it is the only one left for a client.

fail_on_warning=[0|1]

If a warning is generated during a backup, fail the backup. The default is 0. This option can be overridden per-client in the client configuration files in clientconfdir on the server.

## CLIENT CONFIGURATION FILE OPTIONS
. [glob]

Read additional configuration files. On Windows, the glob is unimplemented - you will need to specify an actual file.

mode=client

Required to run in client mode.

server=[host:port]

Defines the server to connect to. If you don't specify a port here, you will need to specify it separately.

server_failover=[host:port]

Defines a failover server to connect to. You can provide more than one 'server_failover' entry. The client will try the next failover server if it fails to connect. IMPORTANT: The burp client currently does not have the capability to have a different SSL profile for each server, so for this to work for you, you will need to have the same CA and certificates on each server.

failover_on_backup_error=[0|1]

Failover to failover servers on backup errors as well as failures to connect. The default is off.

port=[port]

Defines the TCP port on the server that we will send requests to. If this option is set, it is the default for these options, which can be overridden individually: port_backup, port_restore, port_verify, port_list, port_delete. If this option is not set, you will need to set all of the port options separately.

port_backup=[port]

Defines the TCP port on the server that we will send backup requests to. If not set, it defaults to the port option.

port_restore=[port]

Defines the TCP port on the server that we will send restore requests to. If not set, it defaults to the port option.

port_verify=[port]

Defines the TCP port on the server that we will send verify requests to. If not set, it defaults to the port_restore option.

port_list=[port]

Defines the TCP port on the server that we will send list requests to. If not set, it defaults to the port option.

port_delete=[port]

Defines the TCP port on the server that we will send delete requests to. If not set, it defaults to the port option.

status_port=[port]

Defines the TCP port that the server is listening on for status requests.

cname=[client name]

Defines the client name to identify as to the server.

cname_lowercase=[0|1]

Whether to force lowercase cname when detecting cname automatically (ie. no cname provided above). The default is 0. When set to 1 the name returned by the get_fqdn function will be lowercased.

cname_fqdn=[0|1]

Whether to keep fqdn cname (like 'testclient.example.com') when detecting cname automatically (ie. no cname provided above). The default is 1. When set to 0, the fqdn returned by the get_fqdn function will be stripped ('testclient.example.com' becomes 'testclient').

protocol=[0|1|2]

Choose which style of backups and restores to use. 0 (the default) automatically decides based on the server version and which protocol is set on the server side. 1 forces protocol1 style (file level granularity with a pseudo mirrored storage on the server and optional rsync). 2 forces protocol2 style (inline deduplication with variable length blocks). If you choose a forced setting, it will be an error if the server also chooses a forced setting.

password=[password]

Defines the password to send to the server.

enabled=[0|1]

Set this to 0 if you want to disable a client. The default is 1. This option can also be set in the client configuration files in clientconfdir on the server.

lockfile=[path]

Path to the lockfile that ensures that two client processes cannot run simultaneously (this currently doesn't work on Windows).

pidfile=[path]

Synonym for lockfile.

syslog=[0|1]

Log to syslog. Defaults to off.

stdout=[0|1]

Log to stdout. Defaults to on.

progress_counter=[0|1]

Print progress counters on stdout. Defaults to on.

randomise=[max secs]

When running a timed backup, sleep for a random number of seconds (between 0 and the number given) before contacting the server. Alternatively, this can be specified by the '-q' command line option.

user=[username]

Run as a particular user (not supported on Windows).

group=[groupname]

Run as a particular group (not supported on Windows).

ratelimit=[Mb/s]

Set the network send rate limit, in Mb/s. If this option is not given, burp will send data as fast as it can. If you want the client's sending speed to be limited, you will also need to set this option on the client side.

network_timeout=[s]

Set the network timeout in seconds. If no data is sent or received over a period of this length, burp will give up. The default is 7200 seconds (2 hours).

ca_burp_ca=[path]

Path to the burp_ca script (burp_ca.bat on Windows). For more information on this, please see docs/burp_ca.txt.

ca_csr_dir=[path]

Directory where certificate signing requests are generated. For more information on this, please see docs/burp_ca.txt.

ssl_cert_ca=[path]

The path to the SSL CA certificate. This file will probably be the same on both the server and the client. The file should contain just the certificate in PEM format. For more information on this and the other ssl_* options, please see docs/burp_ca.txt.

ssl_cert=[path]

The path to the client SSL certificate. It works for me when the file contains the concatenation of the certificate and private key in PEM format.

ssl_key=[path]

The path to the client SSL private key in PEM format.

ssl_key_password=[password]

Only needed for loading an encrypted certificate.

ssl_cert_password=[password]

Synonym for ssl_key_password.

ssl_peer_cn=[string]

Must match the common name in the SSL certificate that the server gives when it connects. If ssl_peer_cn is not set, the server name will be used instead.

ssl_ciphers=[cipher list]

Allowed SSL ciphers. See openssl ciphers for details.

server_can_override_includes=[0|1]

To prevent the server from being able to override your local include/exclude list, set this to 0. The default is 1.

server_can_restore=[0|1]

To prevent the server from initiating restores, set this to 0. The default is 1. You will also need to give a location for the files to be restored to with the 'restoreprefix' option.

restoreprefix=[path]

When restoring, this path will be prefixed to the restore path. The '-d' command line option overrides this setting. This setting is required if you are using server initiated restores.

encryption_password=[password]

Set this to enable client side file Blowfish encryption. If you do not want encryption, leave this field out of your config file. IMPORTANT: Configuring an encryption_password renders delta differencing pointless, since the smallest real change to a file will make the whole file look different. Therefore, activating this option turns off delta differencing so that whenever a client file changes, the whole new file will be uploaded on the next backup. ALSO IMPORTANT: If you manage to lose your encryption password, you will not be able to unencrypt your files. You should therefore think about having a copy of the encryption password somewhere off-box, in case of your client hard disk failing. Take care when copying and pasting special characters between client conf files, as the encoding of the config file matters. FINALLY: If you change your encryption password, you will end up with a mixture of files on the server with different encryption and it may become tricky to restore more than one file at a time. For this reason, if you change your encryption password, you may want to start a fresh chain of backups (by moving the original set aside, for example). Burp will cope fine with turning the same encryption password on and off between backups, and will restore a backup of mixed encrypted and unencrypted files without a problem. This option is applicable to protocol version 1 only.

glob_after_script_pre=[0|1]

Set this to 0 if you do not want include_glob settings to be evaluated after the pre script is run. The default is 1.

backup_script_pre=[path]

Path to a script to run before a backup. It is not run if the server decides it is not yet time for a backup. The arguments to it are 'pre', 'reserved2' to 'reserved5', and then arguments defined by backup_script_pre_arg - unless the option 'backup_script_reserved_args' is off, then only arguments defined by backup_script_pre_arg are passed to it. If the script fails (ie. when the return code is not 0), then the backup is aborted.

backup_script_pre_arg=[string]

A user-definable argument to the backup pre script. You can have many of these.

backup_script_post=[path]

Path to a script to run after a backup. The arguments to it are 'post', [0|1] if the backup failed or succeeded, 'reserved3' to 'reserved5', and then arguments defined by backup_script_post_arg - unless the option 'backup_script_reserved_args' is off, then only arguments defined by backup_script_post_arg are passed to it.

backup_script_post_arg=[string]

A user-definable argument to the backup post script. You can have many of these.

backup_script_post_run_on_fail=[0|1]

If this is set to 1, backup_script_post will be run whether the backup succeeds or not. The default is 0, which means that backup_script_post will only be run if the backup succeeds.

restore_script_pre=[path]

Path to a script to run before a restore. The arguments to it are 'pre', 'reserved2' to 'reserved5', and then arguments defined by restore_script_pre_arg - unless the option 'restore_script_reserved_args' is off, then only arguments defined by restore_script_pre_arg are passed to it.

restore_script_pre_arg=[string]

A user-definable argument to the restore pre script. You can have many of these.

restore_script_post=[path]

Path to a script to run after a restore. The arguments to it are 'post', [0|1] if the restore failed or succeeded, 'reserved3' to 'reserved5', and then arguments defined by restore_script_post_arg - unless the option 'restore_script_reserved_args' is off, then only arguments defined by restore_script_post_arg are passed to it.

restore_script_post_arg=[string]

A user-definable argument to the restore post script. You can have many of these.

restore_script_post_run_on_fail=[0|1]

If this is set to 1, restore_script_post will be run whether the restore succeeds or not. The default is 0, which means that restore_script_post will only be run if the restore succeeds.

backup_script=[path]

You can use this to save space in your config file when you want to run the same script before and after a backup. It overrides backup_script_pre and backup_script_post.

backup_script_arg=[path]

Goes with backup_script and overrides backup_script_pre_arg and backup_script_post_arg.

backup_script_reserved_args=[0|1]

Whether to pass reserved arguments to backup scripts. The default is on.

restore_script=[path]

You can use this to save space in your config file when you want to run the same script before and after a restore. It overrides restore_script_pre and restore_script_post.

restore_script_arg=[path]

Goes with restore_script and overrides restore_script_pre_arg and restore_script_post_arg.

restore_script_reserved_args=[0|1]

Whether to pass reserved arguments to restore scripts. The default is on.

autoupgrade_dir=[path]

Path to autoupgrade directory into which upgrades are downloaded. Please see docs/autoupgrade.txt in the source package for more help with this option. If you do not want your client to autoupgrade, do not set this option.

autoupgrade_os=[string]

Name of the client operating system. Should match a directory name in the server's autoupgrade_dir. If you do not want your client to autoupgrade, do not set this option.

monitor_exe=[path]

Where to look to find the burp binary to use when forking a monitor client. This might be needed on systems that don't have any sensible way to self-determine a process' own path, such as openbsd.

## INCLUDES / EXCLUDES
The following options specify exactly what is backed up. The client can specify these options, or if you include at least one 'include=' or 'include_glob=' in the client configuration files on the server, the server will override them all.

include=[path]

Path to include in the backup. You can have multiple include lines. Use forward slashes '/', not backslashes '\' as path delimiters.

exclude=[path]

Path to exclude from the backup. You can have multiple exclude lines. Use forward slashes '/', not backslashes '\' as path delimiters.

include_glob=[glob expression]

Include paths that match the glob expression. For example, '/home/*/Documents' will include '/home/user1/Documents' and '/home/user2/Documents' if directories 'user1' and 'user2' exist in '/home'. The Windows implementation currently limits the expression to contain only one '*', with one exception - you may also specify '*:' to expand to detected fixed drives.

include_regex=[regular expression]

Include paths that match the regular expression. You need at least one 'include' or 'include_glob' option to have files to be matched against the regex. If you have at least one 'include_regex' line, then any path NOT matching the regex will be excluded from your backup.

exclude_regex=[regular expression]

Exclude paths that match the regular expression.

include_logic=[logic expression]

Not yet implemented. See 'exclude_logic' for details on the 'logic expression' syntax.

exclude_logic=[logic expression]

Exclude paths that match the 'logic expression'. A 'logic expression' may contain several tests chained with boolean operators. The supported operators are: 'and', 'or', 'not' as well as groups of expressions surrounded by parentheses. The supported tests are: 'file_size', 'file_match', 'path_match' and 'file_ext'. The 'file_size' test supports comparisons with '>', '>=', '<', '<=', '=' and take a size as parameter, example: 'file_size<=5Mb'. The 'file_ext' test takes an extension as parameter, example: 'file_ext=pst'. Finally, the 'file_match' and 'path_match' tests take a regular expression as parameter, example: file_match=b$. 'file_match' is ran against the filename (example 'file1') while 'path_match' is ran against the full path of the file (example: '/home/test/file1'). A complete expression may look like '(file_size>=5Mb and file_size<=10Mb) and (file_ext=pst or file_match=movies) and not file_ext=mp3'. There are some limitations though, white-spaces and parentheses must be escaped inside a test either by quoting the expression or escaping a given character: 'file_match="perso(nnal)?"', 'file_match=a filename'.

include_ext=[extension]

Extensions to include in the backup. Case insensitive. Nothing else will be included in the backup. You can have multiple include extension lines. For example, set 'txt' to include files that end in '.txt'. You need to specify an 'include' line so that burp knows where to start looking.

exclude_ext=[extension]

Extensions to exclude from the backup. Case insensitive. You can have multiple exclude extension lines. For example, set 'vdi' to exclude VirtualBox disk images.

exclude_comp=[extension]

Extensions to exclude from compression. Case insensitive. You can have multiple exclude compression lines. For example, set 'gz' to exclude gzipped files from compression.

exclude_fs=[fstype]

File systems to exclude from the backup. Case insensitive. You can have multiple exclude file system lines. For example, set 'tmpfs' to exclude tmpfs. Burp has an internal mapping of file system names to file system IDs. If you know the file system ID, you can use that instead. For example, 'exclude_fs = 0x01021994' will also exclude tmpfs.

include_fs=[fstype]

File systems to include into the backup. Case insensitive. You can have multiple include file system lines. For example, set 'ext4' to include ext4. Burp has an internal mapping of file system names to file system IDs. If you know the file system ID, you can use that instead. For example, 'include_fs = 0x01021994' will also include tmpfs. If at least one file system is included, all other filesystems will be excluded per default. Included directories that do not live on an included file system will be skipped, even if cross_all_filesystems is enabled and they contain subdirectories with included file systems. Note that on SunOS systems include_fs and exclude_fs will do a case sensitive compare of the string descriptors of the file systems instead of the numeric IDs (see f_basetype member is struct statvfs).

min_file_size=[B/KB/MB/GB]

Do not back up files that are less than the specified size. Example: 'min_file_size = 10MB'. Set to 0 (the default) to have no limit.

max_file_size=[B/KB/MB/GB]

Do not back up files that are greater than the specified size. Example: 'max_file_size = 10MB'. Set to 0 (the default) to have no limit.

cross_filesystem=[path]

Allow backups to cross a particular filesystem mountpoint.

cross_all_filesystems=[0|1]

Allow backups to cross all filesystem mountpoints.

nobackup=[file name]

If this file system entry exists, the content of the directory containing it will not be backed up.

read_fifo=[path]

Do not back up the given fifo itself, but open it for reading and back up the contents as if it were a regular file.

read_all_fifos=[0|1]

Open all fifos for reading and back up the contents as if they were regular files.

read_blockdev=[path]

Do not back up the given block device itself, but open it for reading and back up the contents as if it were a regular file.

read_all_blockdevs=[0|1]

Open all block devices for reading and back up the contents as if they were regular files.

split_vss=[0|1]

When backing up Windows computers with burp protocol 1, this option allows you to save the VSS header data separate from the file data. The default is off, which means that the VSS header data is saved prepended to the file data. This option has no effect in protocol 2.

strip_vss=[0|1]

When backing up Windows computers with burp protocol 1, this option allows you to prevent the VSS header data being backed up. The default is off. To restore a backup that has no VSS information on Windows, you need to give the client the '-x' command line option. This option has no effect in protocol 2.

vss_drives=[list of drive letters]

When backing up Windows computers, this option allows you to specify which drives have VSS snapshots taken of them. If you omit this option, burp will automatically decide based on the 'include' options. If you want no drives to have snapshots taken of them, you can specify '0'.

acl=[0|1]

If acl support is compiled into burp, this allows you to decide whether or not to backup acls at runtime. The default is '1'.

xattr=[0|1]

If xattr support is compiled into burp, this allows you to decide whether or not to backup xattrs at runtime. The default is '1'.

atime=[0|1]

This allows you to control whether the client uses O_NOATIME when opening files and directories. The default is 0, which enables O_NOATIME. This means that the client can read files and directories without updating the access times. However, this is only possible if you are running as root, or are the owner of the file or directory. If this is not the case (perhaps you only have group or world access to the files), you will get errors until you set atime=1. With atime=1, the access times will be updated on the files and directories that get backed up.

scan_problem_raises_error=[0|1]

When enabled, this causes problems in the phase1 scan (such as an 'include' being missing) to be treated as fatal errors. The default is off.

## SERVER CLIENTCONFDIR FILE
For the server to know about clients that can contact it, you need to place a file named after the client in clientconfdir. Files beginning with '.' or ending with '~' are ignored. Directories are also ignored.

The file name must match the name in the 'cname' field on the client.

ssl_peer_cn=[string] must match the common name in the SSL certificate that the client gives when it connects. If ssl_peer_cn is not set, the client name will be used instead (the clientconfdir file name).

The file needs to contain a line like password=[password] that matches the same field on the client, or passwd=[hash] - where the plain text password on the client will be tested against a hash of the kind you might find in /etc/passwd.

Additionally, the following options can be overridden here for each client:

client_can_delete client_can_force_backup client_can_list client_can_monitor client_can_restore client_can_verify client_lockdir compression dedup_group directory directory_tree enabled fail_on_warning hard_quota keep label librsync librsync_max_size manual_delete network_allow network_allow_status notify_failure_arg notify_failure_on_backup_with_failovers_left notify_failure_on_backup_working_dir_deletion notify_failure_script notify_success_arg notify_success_script notify_success_warnings_only password_check path_length_warn protocol rblk_memory_max restore_client server_script_arg server_script server_script_notify server_script_post_arg server_script_post server_script_post_notify server_script_post_run_on_fail server_script_pre_arg server_script_pre server_script_pre_notify soft_quota super_client syslog timer_arg timer_repeat_interval timer_script timestamp_format version_warn working_dir_recovery_method

Additionally, the includes and excludes can be overridden here, as described in the section above.

As with the other configuration files, extra configuration can be included with the '. path/to/config/file' syntax.

## Some notes on SSL certificates
The burp example configs come with example SSL certificates and keys. You can use these and burp will work. But if you are worried about network security, you should generate your own certificates and keys and point your config files to them. To create the example files, I used a handy interface to openssl, called 'tinyca' (http://tinyca.sm-zone.net/). If you are using Debian, you can run 'apt-get install tinyca' to get it. There is also the option of using burp_ca, which you can find in the source distribution, courtesy of Patrick Koppen.

## Examining backups
As well as using the client list options described above, you can go directly to the storage directory on the server. The backups for a client are in the directory named after the client. Inside each backup directory is a file called manifest.gz.

This contains a list of all the files in the backup, and where they originally came from on the client.

There is also a 'log.gz' file in the backup directory, which contains the output generated by the server during the backup.

The 'data' directory contains complete backup files.

The 'deltas.reverse' directory contains reverse deltas that can be applied to the data from the next backup in the sequence (indicated by the contents of the 'forward' file).

Anything with a .gz suffix is compressed in zlib (gzip) format. You can use standard tools, such as zcat, zless or cp, to view them or copy them elsewhere. Files from Windows backups will probably contain VSS headers and/or footers. For help stripping these, see the vss_strip man page.

## Server initiated backups
You can queue a backup on the server, to be performed when the client next makes contact. To do this, you put a file called 'backup' into the top level of the client storage directory. The contents of the file are ignored.

## Server initiated restores
You can queue a restore on the server, to be performed when the client next makes contact. To do this, you put a file called 'restore' into the top level of the client storage directory. The client can deny server initiated restores by setting "server_can_restore=0" in its burp.conf. The client also needs to specify 'restoreprefix' in its configuration as a destination for the restored files. Valid fields to include in the restore file are:

orig_client=[client]

The original client to restore from. Equivalent to '-C' when initiating a restore from a client. Do not include this line when restoring to the original client. See also the 'restore_client' and 'super_client' server options.

backup=[number|a]

The number of the backup to restore from. Equivalent to '-b' when initiating a restore from the client.

overwrite=[0|1]

Whether to overwrite existing files. Equivalent to '-f' when initiating a restore from the client.

strip=[number]

Number of leading path components to strip. Equivalent to '-s' when initiating a restore from the client.

restoreprefix=[path]

Appended to the client-side 'restoreprefix' setting, and then prefixed to the restore path.

stripfrompath=[string]

Strip matching string from restore paths (before prefix is prepended).

regex=[regular expression]

Only restore files matching the regular expression. Equivalent to '-r' when initiating a restore from the client.

include=[path]

Restore directories and files that match the path. If it is a directory, the contents of the directory will be restored. You can have multiple 'include' lines. There is no equivalent when initiating a restore from the client.

## SIGNALS
Sending signal 1 (HUP) to the main server process will cause it to reload. For the vast majority of configuration changes, a reload is unnecessary as the server will pick up changes "on-the-fly". Sending signal 12 (USR2) to the main server process will cause it to wait until there are no longer any child processes, and then exit. The intention is to help with upgrades without interrupting current backups. if you are running upstart, a new burp server process will start up when the old one exits.

## RETURN CODES (SERVER)
0: success

1: error

## RETURN CODES (CLIENT)
0: success

1: error

2: restore gave warnings

3: timer conditions on the server were not met

4: could not connect to server

5: max parallel backups reached

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.

branch: sisyphus


title: burp_ca(8)

text:
# burp_ca(8)

## NAME
burp_ca - program for generating certificates for use with burp

## SYNOPSIS
burp_ca [options]

A script for generating certificates for use with burp. This script comes with the burp backup and restore package, and was contributed by Patrick Koppen.

## OPTIONS
-h|--help

show help

-i|--init

inititalize CA

-k|--key

generate new key

-r|--request

generate certificate sign request

-s|--sign

sign csr (use --ca <ca> and --name <name>)

--batch do not prompt for anything

--revoke <number> revoke certificate with serial number

--crl generate certificate revoke list

-d|--dir <dir>

ca output dir (default: /etc/burp/CA)

-c|--config

config file (default: /etc/burp/CA.cnf)

-n|--name

name (default: builder)

-D|--days

valid days for certificate (default in config file)

--ca_days valid days for CA certificate (default: 3650)

-S|--size

key size (default: 2048)

-a|--ca

ca name if different from name

-f|--dhfile <path>

generate a new dhfile

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
Patrick Koppen wrote burp_ca. The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.


title: vss_strip(8)

text:
# vss_strip(8)

## NAME
vss_strip - program for extracting file data from a file containing VSS headers

## SYNOPSIS
vss_strip [options]

A program for extracting file data from a file containing VSS headers. This program comes with the burp backup and restore package.

## OPTIONS
-i path

Input file. If -i is not given, input will be read on stdin.

-o path

Output file. If -o is not given, output will be read on stdout.

-p

Print VSS header info.

-h|-?

Print help text and exit.

## EXAMPLES
vss_strip -i infile -o outfile

Takes uncompressed infile, and extracts the file data to outfile.

zcat infile.gz | vss_strip

Takes the output of zcat as input, and outputs to stdout.

## BUGS
If you find bugs, please report them to the email list. See the website <http://burp.grke.net/> for details.

## AUTHOR
The main author of Burp is Graham Keeling.

## COPYRIGHT
See the LICENCE file included with the source distribution.


bwping

package: bwping

title: bwping(8)

text:
# bwping(8)

## NAME
bwping and bwping6 are tools to measure bandwidth and response times between two hosts using Internet Control Message Protocol (ICMP) echo request/echo reply mechanism. bwping deals with IPv4 networks, while bwping6 - with IPv6 networks.

## SYNOPSIS
bwping [ -u bufsize ] [ -r reporting_period ] [ -T tos ] [ -B bind_addr ] -b kbps -s pktsize -v volume target

bwping6 [ -u bufsize ] [ -r reporting_period ] [ -T tclass ] [ -B bind_addr ] -b kbps -s pktsize -v volume target

## OPTIONS
-u bufsize

Sets the send/receive buffer size in bytes. Default value will be automatically calculated based on transfer speed, packet size and host timer accuracy.

-r reporting_period

Sets the interval time in seconds between periodic bandwidth, RTT, and loss reports. If zero, there will be no periodic reports (default).

-T tos (bwping only)

Sets the TOS value of outgoing ip packets. Default value is zero.

-T tclass (bwping6 only)

Sets the IPv6 Traffic Class value of outgoing ip packets. Default value is zero.

-B bind_addr

Sets the source address of outgoing ip packets. By default the address of the outgoing interface will be used.

-b kbps

Sets the transfer speed in kilobits per second.

-s pktsize

Sets the packet size in bytes.

-v volume

Sets the volume to transfer in bytes.

## AUTHORS
Oleg Derevenetz <oleg.derevenetz@gmail.com>

## BUGS
None known.

## RESTRICTIONS
This utility uses raw sockets to deal with ICMP messages, so root privileges are required to run it.

Although bwping and bwping6 does not require any special software on the remote host (only the ability to respond on ICMP echo request messages), there are some special requirements to network infrastructure, local and remote host performance:

1. There should be no ICMP echo request/reply filtering on the network. This includes QoS mechanisms (which often affects ICMP) at any point in the testing path;

2. Local host should have enough CPU resources to send ICMP echo request messages with given rate, and remote host should quickly respond on these messages and should have no ICMP bandwidth limiting turned on.

If some of these requirements are not satisfied, then measurement results will be inadequate or fail completely. In general, for testing bandwidth where QoS is implemented, always test with traffic that matches the QoS class to be tested.

## SEE ALSO
netstat(1), ping(8)


title: bwping6(8)

text:
# bwping6(8)

## NAME
bwping and bwping6 are tools to measure bandwidth and response times between two hosts using Internet Control Message Protocol (ICMP) echo request/echo reply mechanism. bwping deals with IPv4 networks, while bwping6 - with IPv6 networks.

## SYNOPSIS
bwping [ -u bufsize ] [ -r reporting_period ] [ -T tos ] [ -B bind_addr ] -b kbps -s pktsize -v volume target

bwping6 [ -u bufsize ] [ -r reporting_period ] [ -T tclass ] [ -B bind_addr ] -b kbps -s pktsize -v volume target

## OPTIONS
-u bufsize

Sets the send/receive buffer size in bytes. Default value will be automatically calculated based on transfer speed, packet size and host timer accuracy.

-r reporting_period

Sets the interval time in seconds between periodic bandwidth, RTT, and loss reports. If zero, there will be no periodic reports (default).

-T tos (bwping only)

Sets the TOS value of outgoing ip packets. Default value is zero.

-T tclass (bwping6 only)

Sets the IPv6 Traffic Class value of outgoing ip packets. Default value is zero.

-B bind_addr

Sets the source address of outgoing ip packets. By default the address of the outgoing interface will be used.

-b kbps

Sets the transfer speed in kilobits per second.

-s pktsize

Sets the packet size in bytes.

-v volume

Sets the volume to transfer in bytes.

## AUTHORS
Oleg Derevenetz <oleg.derevenetz@gmail.com>

## BUGS
None known.

## RESTRICTIONS
This utility uses raw sockets to deal with ICMP messages, so root privileges are required to run it.

Although bwping and bwping6 does not require any special software on the remote host (only the ability to respond on ICMP echo request messages), there are some special requirements to network infrastructure, local and remote host performance:

1. There should be no ICMP echo request/reply filtering on the network. This includes QoS mechanisms (which often affects ICMP) at any point in the testing path;

2. Local host should have enough CPU resources to send ICMP echo request messages with given rate, and remote host should quickly respond on these messages and should have no ICMP bandwidth limiting turned on.

If some of these requirements are not satisfied, then measurement results will be inadequate or fail completely. In general, for testing bandwidth where QoS is implemented, always test with traffic that matches the QoS class to be tested.

## SEE ALSO
netstat(1), ping(8)


c-icap

package: c-icap

title: c-icap(8)

text:
# c-icap(8)

## NAME
c-icap - ICAP filtering server

## SYNOPSIS
c-icap [ -V ] [ -VV ] [ -f config-file ] [ -N ] [ -d debug-level ] [ -D ]

## DESCRIPTION
c-icap is an implementation of an ICAP server. It can be used with HTTP proxies that support the ICAP protocol. Most of the comercial HTTP proxies must support ICAP pcotocol.

## OPTIONS
-V

Print version

-VV

Print build informations

-f config-file

Specify the configuration file

-N

Do not run as daemon

-d level

Specify the debug level

-D

Print debug info to stdout

## FILES
/etc/c-icap.conf

The main configuration file

/etc/c-icap.magic

In this file defined the types of files and the groups of file types.

/run/c-icap.pid By default c-icap writes its pid in this file. The path of this file can changed using the PidFile configuration parameter in the c-icap.conf file

/run/c-icap.ctl The commands socket. This file used to send commands to the icap server from command line. For information about implemented commands look below in the "Implemented commands" sub-section

## NOTES

### Implemented commands
Currently the following commands are implemented:

stop

The c-icap will shutdown

reconfigure

The service will reread the config file without the need to stop and restart the c-icap server. The services will be reinitialized

relog

This command causes c-icap to close and reopen the log files. This is very useful for log rotation.

Services and modules can define their own commands.

Examples:

To reconfigure c-icap:

echo -n "reconfigure" > /run/c-icap.ctl

To rotate access log:

mv /var/log/c-icap/access.log /var/log/c-icap/access.log.1

echo -n "relog" > /run/c-icap.ctl

### Lookup tables
Lookup tables are simple read-only databases. A lookup table can defined in c-icap.conf file using the form:

type:path

where the type is the type of lookup table and path is the extra information required to use the table (e.g. file path). Currently the following lookup table types defined internally by c-icap:

file

Simple text file databases. The database records are stored in text files in the form:

key[: value1, value2 ...]

example path definition:

file:/path/to/the/file.txt

hash

Similar to file lookup tables but c-icap uses fast hashes for searching.

example path definition:

hash:/path/to/the/file.txt

regex

Similar to the file lookup tables but the keys are regular expressions in the form /regex/flags . For possible flags values please read 'Regex expressions' paragraph in this manual.

example regex lookup table data:

/^[a-m].*/i: group1

/^[n-z].*/i: group2

example path definition:

regex:/path/to/the/file.txt

### Regex expressions
The c-icap regex expressions have the form /regex_definition/flags where "flags" is one or more letters, its of them express a flag.

Common flags

g This flag forces the score multiplied by the number of regex

expression matches. For example if the expression matches 5

times and the devined score value is 10 then the final score

will be 50.

i Do caseless matching

m Match-any-character operators don't match a newline

and ^$ operators does not match newlines within data

If the module compiled using the pcre library the following flags can be used

s (PCRE_DOTALL) matches anything including NL

x (PCRE_EXTENDED) Ignore whitespace and # comments

A (PCRE_ANCHORED) Force pattern anchoring

D (PCRE_DOLLAR_ENDONLY) $ not to match newline at end

U (PCRE_UNGREEDY) Invert greediness of quantifiers

X (PCRE_EXTRA) PCRE extra features

u (PCRE_UTF8) Run in UTF-8 mode

### Runtime information
Someone can retrieve runtime information using the info service. The information includes bytes received and transmited, active services, information about service usage and many other. The information provided in HTML and text format.

Example:

Retrieve runtime information from command line:

c-icap-client -i localhost -s "info?view=text" -req "a_url"

## SEE ALSO
c-icap-client(8) c-icap-stretch(8) c-icap-config(8) c-icap-libicapapi-config(8) c-icap-mkbdb(8)

## BUGS
Many...

## AUTHOR
Tsantilas Christos


c-icap-client

title: c-icap-client(8)

text:
# c-icap-client(8)

## NAME
c-icap-client - simple ICAP client

## SYNOPSIS
c-icap-client [ -V ] [ -VV ] [ -i icap_servername ] [ -p port ] [ -s service ] [ -tls ] [ -tls-method method ] [ -tls-no-verify ] [ -f input_file ] [ -o out_file ] [ -req url ] [ -resp url ] [ -d debug level ] [ -noreshdr ] [ -nopreview ] [ -no204 ] [ -206 ] [ -x icap-header ] [ -hx http-request-header ] [ -rhx http-response-header ] [ -w preview_size ] [ -v ]

## DESCRIPTION
c-icap-client is a simple ICAP client. It can be used to test your icap server configuration.

## OPTIONS
-V

Print version

-VV

Print build informations

-i icap_servername

The hostname of the icap server. The default is localhost

-p port

The server port. The default port value is 1344

-s service

The service name. The default service name is "echo"

-tls

Use TLS

-tls-method method

Select the TLS method to use, normaly one of TLSv1, TLSv1_1, TLSv1_2 or TLSv1_3

-tls-no-verify

Disable TLS server certificate verify

-f filename

Send this file to the icap server. Default is to send an options request

-o filename

Save output to this file. Default is to send to stdout

-req url

Send a request modification instead of response modification, using as http url the url provided with this option.

-resp url

Send a response modification with http request headers, using as http url the url provided with this option.

-d level

debug level info to stdout

-noreshdr

Do not send reshdr headers

-nopreview

Do not send preview request data

-no204

Do not allow204 outside preview

-206

Support 206 responses

-x icap-header

Include the icap-header in icap request headers

-hx http-request-header

Include the http-request-header in http request headers

-rhx http-response-header

Include the http-response-header in http response headers

-w preview

Sets the maximum preview data size to preview

-v

Print response headers

## SEE ALSO
c-icap(8) c-icap-stretch(8) c-icap-config(8) c-icap-libicapapi-config(8) c-icap-mkbdb(8)

## BUGS
Many...

## AUTHOR
Tsantilas Christos


c-icap-config

title: c-icap-config(8)

text:
# c-icap-config(8)

## NAME
c-icap-config - script to get information about c-icap server

## SYNOPSIS
c-icap-config [ --cflags ] [ --libs ] [ --datarootdir ] [ --configdir ] [ --version ] [ --config ]

## DESCRIPTION
c-icap-config is a script to get information about c-icap server and compile options must used to build c-icap server modules and services.

## OPTIONS
--cflags

print preprocessor and compiler flags should used to compile a c-icap service or module

--libs

print linker flags should used to build a c-icap service or module

--datarootdir

print the c-icap data directory

--configdir

print the c-icap configuration directory

--version

print the c-icap server version

--config

print the c-icap server compile configuration

## SEE ALSO
c-icap(8) c-icap-client(8) c-icap-stretch(8) c-icap-libicapapi-config(8) c-icap-mkbdb(8)

## AUTHOR
Tsantilas Christos


c-icap-libicapapi-config

title: c-icap-libicapapi-config(8)

text:
# c-icap-libicapapi-config(8)

## NAME
c-icap-libicapapi-config - script to get information about c-icap library

## SYNOPSIS
c-icap-libicapapi-config [ --cflags ] [ --libs ] [ --version ]

## DESCRIPTION
c-icap-libicapapi-config is a script to get compile options must used to use c-icap library.

## OPTIONS
--cflags

print preprocessor and compiler flags should used to compile a c-icap service or module

--libs

print linker flags should used to link with c-icap library

--version

print the c-icap server version

## SEE ALSO
c-icap(8) c-icap-client(8) c-icap-stretch(8) c-icap-config(8) c-icap-mkbdb(8)

## AUTHOR
Tsantilas Christos


c-icap-mkbdb

title: c-icap-mkbdb(8)

text:
# c-icap-mkbdb(8)

## NAME
c-icap-mkbdb - simple ICAP clientutility to create Berkeley DB lookup tables

## SYNOPSIS
c-icap-mkbdb [ -V ] [ -VV ] [ -d debug_level ] [ -i file.txt ] [ -o file.db ] [ -t string|int|ip ] [ -v string|int|ip ] [ --dump ]

## DESCRIPTION
c-icap-mkbdb utility can be used to create Berkeley DB databases which can be used as lookup tables by the c-icap server.

## OPTIONS
-V

Print version

-VV

Print build informations

-d debug_level

The debug level

-i file.txt

The file contains the data (required). The line format of this file must be:

key: value1, value2, ....

-o file.db

The database to be created

-t string|int|ip

The type of the key. Select string for string keys, int for integer keys or ip for using IP addresses as keys. The "string" is the default.

-v string|int|ip

The type of the values. The "string" is the default.

-p page_size[k]

The page size to use. Can not be less than 512 bytes or greater than 64k. Read berkeleyDB manual for default values.

--btree

Use B-Tree as access method for the database. By default uses Hash.

--dump

Do not update the database just dump it to the screen.

## EXAMPLES
c-icap-mkbdb -o keys -i keys.txt

It builds the keys Berkeley DB database, using string type for keys and values.

c-icap-mkbdb -o keys --dump

Dump the contents of the keys database

## SEE ALSO
c-icap(8) c-icap-client(8) c-icap-stretch(8) c-icap-config(8) c-icap-libicapapi-config(8)

## AUTHOR
Tsantilas Christos


c-icap-stretch

title: c-icap-stretch(8)

text:
# c-icap-stretch(8)

## NAME
c-icap-stretch - A simple utility for stretching ICAP servers

## SYNOPSIS
c-icap-stretch [ -V ] [ -VV ] [ -i icap_servername ] [ -p port ] [ -s service ] [ -urls filename ] [ -req ] [ -m max-requests ] [ -t threads-number ] [ -d debug level ] [ -x icap-header ] [ -hx http-request-header ] [ -rhx http-response-header ] file1 file2 ...

## DESCRIPTION
c-icap-stretch is a simple utility for loading ICAP servers.

## OPTIONS
-V

Print version

-VV

Print build informations

-i icap_servername

The hostname of the icap server. The default is localhost

-p port

The server port. The default port value is 1344

-s service

The service name. The default service name is "echo"

-urls filename

File with urls, one url per line, to use for stress test

-req

Send request modification requests

-m max-requests

The maximum requests to send

-t threads-number

The number of client threads to start

-d level

debug level info to stdout

-x icap-header

Include the icap-header in icap request headers

-hx http-request-header

Include the http-request-header in http request headers

-rhx http-response-header

Include the http-response-header in http response headers

file1 file2 ...

The files to use as body data to the ICAP requests.

## SEE ALSO
c-icap(8) c-icap-client(8) c-icap-config(8) c-icap-libicapapi-config(8) c-icap-mkbdb(8)

## BUGS
It can used only for ICAP response modification services.

## AUTHOR
Tsantilas Christos


c-icap-mods-sguardDB

package: c-icap-modules

title: c-icap-mods-sguardDB(8)

text:
# c-icap-mods-sguardDB(8)

## NAME
c-icap-mods-sguardDB - simple utility to create Berkeley DB lookup tables

## SYNOPSIS
c-icap-mods-sguardDB [ -d debug_level ] [ -db path ] [ -C ] [ -u ] [ -s url ] [ -f urls|domains ] [ --dump ]

## DESCRIPTION
c-icap-mods-sguardDB utility can be used to create SquidGuard databases which can be used with url_check service.

## OPTIONS
-d debug_level

The debug level to use

-db path

The database path

-C

Create mode. Create the database using the "domains" and "urls" files exist under the database directory.

-u

Update mode. Update the database using the "domains.diff" and "urls.diff" files exist under th database directory. Each diff file consist by lines starting from "+" to mark a url or a domain to be appended to the database or "-" to mark a domain or url to be removed from database.

-s url

Search in the database for a url or domain matches the given url

-f urls|domains

Select the sub-database (urls or domains) to operate.

## EXAMPLES
c-icap-mods-sguardDB -C -db /url/local/blacklists-toulouse/porn/

It builds the domains.db and urls.db SquidGuard databases under the /url/local/blacklists-toulouse/porn directory using the urls and domains files exist under the same directory.

c-icap-mods-sguardDB -u -db /url/local/blacklists-toulouse/porn/

updates the SquidGuard databases under the /url/local/blacklists-toulouse/porn directory using the urls.diff and domains.diff files exist under the same directory.

## SEE ALSO
c-icap(8)

## AUTHOR
Tsantilas Christos


update-ca-trust

package: ca-trust

title: update-ca-trust(8)

text:
# update-ca-trust(8)

## NAME
update-ca-trust - manage consolidated and dynamic configuration of CA certificates and associated trust

## SYNOPSIS
update-ca-trust [extract] [-o DIR|--output=DIR]

## DESCRIPTION
update-ca-trust(8) is used to manage a consolidated and dynamic configuration feature of Certificate Authority (CA) certificates and associated trust.

The feature is available for new applications that read the consolidated configuration files found in the /etc/pki/ca-trust/extracted directory or that load the PKCS#11 module p11-kit-trust.so

Parts of the new feature are also provided in a way to make it useful for legacy applications.

Many legacy applications expect CA certificates and trust configuration in a fixed location, contained in files with particular path and name, or by referring to a classic PKCS#11 trust module provided by the NSS cryptographic library.

The dynamic configuration feature provides functionally compatible replacements for classic configuration files and for the classic NSS trust module named libnssckbi.

In order to enable legacy applications, that read the classic files or access the classic module, to make use of the new consolidated and dynamic configuration feature, the classic filenames have been changed to symbolic links. The symbolic links refer to dynamically created and consolidated output stored below the /etc/pki/ca-trust/extracted directory hierarchy.

The output is produced using the update-ca-trust command (without parameters), or using the update-ca-trust extract command. In order to produce the output, a flexible set of source configuration is read, as described in section SOURCE CONFIGURATION.

In addition, the classic PKCS#11 module is replaced with a new PKCS#11 module (p11-kit-trust.so) that dynamically reads the same source configuration.

## SOURCE CONFIGURATION
The dynamic configuration feature uses several source directories that will be scanned for any number of source files. It is important to select the correct subdirectory for adding files, as the subdirectory defines how contained certificates will be trusted or distrusted, and which file formats are read.

Files in subdirectories below the directory hierarchy /usr/share/pki/ca-trust-source/ contain CA certificates and trust settings in the PEM file format. The trust settings found here will be interpreted with a low priority.

Files in subdirectories below the directory hierarchy /etc/pki/ca-trust/source/ contain CA certificates and trust settings in the PEM file format. The trust settings found here will be interpreted with a high priority.

You may use the following rules of thumb to decide, whether your configuration files should be added to the /etc or rather to the /usr directory hierarchy:

•If you are manually adding a configuration file to a system, you probably want it to override any other default configuration, and you most likely should add it to the respective subdirectory in the /etc hierarchy.

•If you are creating a package that provides additional root CA certificates, that is intended for distribution to several computer systems, but you still want to allow the administrator to override your list, then your package should add your files to the respective subdirectory in the /usr hierarchy.

•If you are creating a package that is supposed to override the default system trust settings, that is intended for distribution to several computer systems, then your package should install the files to the respective subdirectory in the /etc hierarchy.

QUICK HELP 1: To add a certificate in the simple PEM or DER file formats to the list of CAs trusted on the system:

•add it as a new file to directory /etc/pki/ca-trust/source/anchors/

•run update-ca-trust extract

QUICK HELP 2: If your certificate is in the extended BEGIN TRUSTED file format (which may contain distrust/blocklist trust flags, or trust flags for usages other than TLS) then:

•add it as a new file to directory /etc/pki/ca-trust/source/

•run update-ca-trust extract

In order to offer simplicity and flexibility, the way certificate files are treated depends on the subdirectory they are installed to.

•simple trust anchors subdirectory: /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/

•simple blocklist (distrust) subdirectory: /usr/share/pki/ca-trust-source/blocklist/ or /etc/pki/ca-trust/source/blocklist/

•extended format directory: /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/

In the main directories /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/ you may install one or multiple files in the following file formats:

•certificate files that include trust flags, in the BEGIN/END TRUSTED CERTIFICATE file format (any file name), which have been created using the openssl x509 tool and the -addreject -addtrust options. Bundle files with multiple certificates are supported.

•files in the p11-kit file format using the .p11-kit file name extension, which can (e.g.) be used to distrust certificates based on serial number and issuer name, without having the full certificate available. (This is currently an undocumented format, to be extended later. For examples of the supported formats, see the files shipped with the ca-certificates package.)

•certificate files without trust flags in either the DER file format or in the PEM (BEGIN/END CERTIFICATE) file format (any file name). Such files will be added with neutral trust, neither trusted nor distrusted. They will simply be known to the system, which might be helpful to assist cryptographic software in constructing chains of certificates. (If you want a CA certificate in these file formats to be trusted, you should remove it from this directory and move it to the ./anchors subdirectory instead.)

In the anchors subdirectories /usr/share/pki/ca-trust-source/anchors/ or /etc/pki/ca-trust/source/anchors/ you may install one or multiple certificates in either the DER file format or in the PEM (BEGIN/END CERTIFICATE) file format. Each certificate will be treated as trusted for all purposes.

In the blocklist subdirectories /usr/share/pki/ca-trust-source/blocklist/ or /etc/pki/ca-trust/source/blocklist/ you may install one or multiple certificates in either the DER file format or in the PEM (BEGIN/END CERTIFICATE) file format. Each certificate will be treated as distrusted for all purposes.

Please refer to the x509(1) manual page for the documentation of the BEGIN/END CERTIFICATE and BEGIN/END TRUSTED CERTIFICATE file formats.

Applications that rely on a static file for a list of trusted CAs may load one of the files found in the /etc/pki/ca-trust/extracted directory. After modifying any file in the /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/ directories or in any of their subdirectories, or after adding a file, it is necessary to run the update-ca-trust extract command, in order to update the consolidated files in /etc/pki/ca-trust/extracted/ .

Applications that load the classic PKCS#11 module using filename libnssckbi.so (which has been converted into a symbolic link pointing to the new module) and any application capable of loading PKCS#11 modules and loading p11-kit-trust.so, will benefit from the dynamically merged set of certificates and trust information stored in the /usr/share/pki/ca-trust-source/ and /etc/pki/ca-trust/source/ directories.

## EXTRACTED CONFIGURATION
The directory /etc/pki/ca-trust/extracted/ contains generated CA certificate bundle files which are created and updated, based on the SOURCE CONFIGURATION by running the update-ca-trust extract command.

If your application isn’t able to load the PKCS#11 module p11-kit-trust.so, then you can use these files in your application to load a list of global root CA certificates.

Please never manually edit the files stored in this directory, because your changes will be lost and the files automatically overwritten, each time the update-ca-trust extract command gets executed.

In order to install new trusted or distrusted certificates, please rather install them in the respective subdirectory below the /usr/share/pki/ca-trust-source/ or /etc/pki/ca-trust/source/ directories, as described in the SOURCE CONFIGURATION section.

The directory /etc/pki/ca-trust/extracted/java/ contains a CA certificate bundle in the java keystore file format. Distrust information cannot be represented in this file format, and distrusted certificates are missing from these files. File cacerts contains CA certificates trusted for TLS server authentication.

The directory /etc/pki/ca-trust/extracted/openssl/ contains CA certificate bundle files in the extended BEGIN/END TRUSTED CERTIFICATE file format, as described in the x509(1) manual page. File ca-bundle.trust.crt contains the full set of all trusted or distrusted certificates, including the associated trust flags.

The directory /etc/pki/ca-trust/extracted/pem/ contains CA certificate bundle files in the simple BEGIN/END CERTIFICATE file format, as described in the x509(1) manual page. Distrust information cannot be represented in this file format, and distrusted certificates are missing from these files. File tls-ca-bundle.pem contains CA certificates trusted for TLS server authentication. File email-ca-bundle.pem contains CA certificates trusted for E-Mail protection. File objsign-ca-bundle.pem contains CA certificates trusted for code signing.

The directory /etc/pki/ca-trust/extracted/edk2/ contains a CA certificate bundle ("cacerts.bin") in the "sequence of EFI_SIGNATURE_LISTs" format, defined in the UEFI-2.7 specification, sections "31.4.1 Signature Database" and "EFI_CERT_X509_GUID". Distrust information cannot be represented in this file format, and distrusted certificates are missing from these files. File "cacerts.bin" contains CA certificates trusted for TLS server authentication.

## COMMANDS

### (absent/empty command)
Same as the extract command described below. (However, the command may print fewer warnings, as this command is being run during rpm package installation, where non-fatal status output is undesired.)

### extract
Instruct update-ca-trust to scan the SOURCE CONFIGURATION and produce updated versions of the consolidated configuration files stored below the /etc/pki/ca-trust/extracted directory hierarchy.

EXTRACT OPTIONS

-o DIR, --output=DIR

Write the extracted trust store into the given directory instead of updating /etc/pki/ca-trust/extracted.

## FILES
/etc/pki/tls/certs/ca-bundle.crt

Classic filename, file contains a list of CA certificates trusted for TLS server authentication usage, in the simple BEGIN/END CERTIFICATE file format, without distrust information. This file is a symbolic link that refers to the consolidated output created by the update-ca-trust command.

/etc/pki/tls/certs/ca-bundle.trust.crt

Classic filename, file contains a list of CA certificates in the extended BEGIN/END TRUSTED CERTIFICATE file format, which includes trust (and/or distrust) flags specific to certificate usage. This file is a symbolic link that refers to the consolidated output created by the update-ca-trust command.

/etc/pki/java/cacerts

Classic filename, file contains a list of CA certificates trusted for TLS server authentication usage, in the Java keystore file format, without distrust information. This file is a symbolic link that refers to the consolidated output created by the update-ca-trust command.

/usr/share/pki/ca-trust-source

Contains multiple, low priority source configuration files as explained in section SOURCE CONFIGURATION. Please pay attention to the specific meanings of the respective subdirectories.

/etc/pki/ca-trust/source

Contains multiple, high priority source configuration files as explained in section SOURCE CONFIGURATION. Please pay attention to the specific meanings of the respective subdirectories.

/etc/pki/ca-trust/extracted

Contains consolidated and automatically generated configuration files for consumption by applications, which are created using the update-ca-trust extract command. Don’t edit files in this directory, because they will be overwritten. See section EXTRACTED CONFIGURATION for additional details.

## AUTHOR
Written by Kai Engert and Stef Walter.


cachefilesd

package: cachefilesd

title: cachefilesd(8)

summary: CacheFiles userspace management daemon

text:
# cachefilesd(8)

## NAME
cachefilesd - CacheFiles userspace management daemon

## SYNOPSIS
cachefilesd [-d]* [-s] [-n] [-N] [-f <configfile>]

## DESCRIPTION
The cachefilesd daemon manages the cache data store that is used by network filesystems such a AFS and NFS to cache data locally on disk.

The README file should be read before attempting to configure this facility:

/usr/share/doc/cachefilesd/README

## OPTIONS
-d

Turn on debugging mode (message written to stderr).

-s

Don't use syslog.

-n

Don't daemonise.

-N

Disable culling and scanning to fill the cull table.

-p <pidfile>

Use an alternate PID file to /var/run/cachefilesd.pid.

-f <configfile>

Read the alternate configuration files.

## FILES
/etc/cachefilesd.conf

## SEE ALSO
cachefilesd.conf(5), /usr/share/doc/cachefilesd/README

## AUTHORS
David Howells <dhowells@redhat.com>


caddy

package: caddy

title: caddy(8)

text:
# caddy(8)

## NAME
caddy -

## SYNOPSIS
caddy [flags]

## DESCRIPTION
Caddy is an extensible server platform written in Go.

At its core, Caddy merely manages configuration. Modules are plugged in statically at compile-time to provide useful functionality. Caddy's standard distribution includes common modules to serve HTTP, TLS, and PKI applications, including the automation of certificates.

To run Caddy, use:

```
- 'caddy run' to run Caddy in the foreground (recommended).
- 'caddy start' to start Caddy in the background; only do this

  if you will be keeping the terminal window open until you run

  'caddy stop' to close the server.
```

When Caddy is started, it opens a locally-bound administrative socket to which configuration can be POSTed via a restful HTTP API (see https://caddyserver.com/docs/api).

Caddy's native configuration format is JSON. However, config adapters can be used to convert other config formats to JSON when Caddy receives its configuration. The Caddyfile is a built-in config adapter that is popular for hand-written configurations due to its straightforward syntax (see https://caddyserver.com/docs/caddyfile). Many third-party adapters are available (see https://caddyserver.com/docs/config-adapters). Use 'caddy adapt' to see how a config translates to JSON.

For convenience, the CLI can act as an HTTP client to give Caddy its initial configuration for you. If a file named Caddyfile is in the current working directory, it will do this automatically. Otherwise, you can use the --config flag to specify the path to a config file.

Some special-purpose subcommands build and load a configuration file for you directly from command line input; for example:

```
- caddy file-server
- caddy reverse-proxy
- caddy respond
```

These commands disable the administration endpoint because their configuration is specified solely on the command line.

In general, the most common way to run Caddy is simply:

```
$ caddy run
```

Or, with a configuration file:

```
$ caddy run --config caddy.json
```

If running interactively in a terminal, running Caddy in the background may be more convenient:

```
$ caddy start
...
$ caddy stop
```

This allows you to run other commands while Caddy stays running. Be sure to stop Caddy before you close the terminal!

Depending on the system, Caddy may need permission to bind to low ports. One way to do this on Linux is to use setcap:

```
$ sudo setcap cap_net_bind_service=+ep $(which caddy)
```

Remember to run that command again after replacing the binary.

See the Caddy website for tutorials, configuration structure, syntax, and module documentation: https://caddyserver.com/docs/

Custom Caddy builds are available on the Caddy download page at: https://caddyserver.com/download

The xcaddy command can be used to build Caddy from source with or without additional plugins: https://github.com/caddyserver/xcaddy

Where possible, Caddy should be installed using officially-supported package installers: https://caddyserver.com/docs/install

Instructions for running Caddy in production are also available: https://caddyserver.com/docs/running

## OPTIONS
-h, --help[=false] help for caddy

## EXAMPLE

```
  $ caddy run

  $ caddy run --config caddy.json

  $ caddy reload --config caddy.json

  $ caddy stop
```

## SEE ALSO
caddy-adapt(8), caddy-add-package(8), caddy-build-info(8), caddy-completion(8), caddy-environ(8), caddy-file-server(8), caddy-fmt(8), caddy-hash-password(8), caddy-list-modules(8), caddy-manpage(8), caddy-reload(8), caddy-remove-package(8), caddy-respond(8), caddy-reverse-proxy(8), caddy-run(8), caddy-start(8), caddy-stop(8), caddy-storage(8), caddy-trust(8), caddy-untrust(8), caddy-upgrade(8), caddy-validate(8), caddy-version(8)

## HISTORY
2-Jul-2026 Auto generated by spf13/cobra


caddy-adapt

title: caddy-adapt(8)

text:
# caddy-adapt(8)

## NAME
caddy-adapt - Adapts a configuration to Caddy's native JSON

## SYNOPSIS
caddy adapt --config [--adapter ] [--pretty] [--validate] [--envfile ] [flags]

## DESCRIPTION
Adapts a configuration to Caddy's native JSON format and writes the output to stdout, along with any warnings to stderr.

If --pretty is specified, the output will be formatted with indentation for human readability.

If --validate is used, the adapted config will be checked for validity. If the config is invalid, an error will be printed to stderr and a non- zero exit status will be returned.

If --envfile is specified, an environment file with environment variables in the KEY=VALUE format will be loaded into the Caddy process.

If you wish to use stdin instead of a regular file, use - as the path.

## OPTIONS
-a, --adapter="caddyfile" Name of config adapter

-c, --config="" Configuration file to adapt (required)

--envfile=[] Environment file(s) to load

-h, --help[=false] help for adapt

-p, --pretty[=false] Format the output for human readability

--validate[=false] Validate the output

## SEE ALSO
caddy(8)

## HISTORY
2-Jul-2026 Auto generated by spf13/cobra


caddy-add-package

title: caddy-add-package(8)

text:
# caddy-add-package(8)

## NAME
caddy-add-package - Adds Caddy packages (EXPERIMENTAL)

## SYNOPSIS
caddy add-package [flags]

## DESCRIPTION
Downloads an updated Caddy binary with the specified packages (module/plugin) added, with an optional version specified (e.g., "package@version"). Retains existing packages. Returns an error if any of the specified packages are already included. EXPERIMENTAL: May be changed or removed.

## OPTIONS
-h, --help[=false] help for add-package

-k, --keep-backup[=false] Keep the backed up binary, instead of deleting it

## SEE ALSO
caddy(8)

## HISTORY
2-Jul-2026 Auto generated by spf13/cobra


caddy-build-info

title: caddy-build-info(8)

text:
# caddy-build-info(8)

## NAME
caddy-build-info - Prints information about this build

## SYNOPSIS
caddy build-info [flags]

## DESCRIPTION
Prints information about this build

## OPTIONS
-h, --help[=false] help for build-info

## SEE ALSO
caddy(8)

## HISTORY
2-Jul-2026 Auto generated by spf13/cobra


caddy-completion

title: caddy-completion(8)

text:
# caddy-completion(8)

## NAME
caddy-completion - Generate completion script

## SYNOPSIS
caddy completion [bash|zsh|fish|powershell]

## DESCRIPTION
To load completions:

```
Bash:

  $ source <(caddy completion bash)

  # To load completions for each session, execute once:

  # Linux:

  $ caddy completion bash > /etc/bash_completion.d/caddy

  # macOS:

  $ caddy completion bash > $(brew --prefix)/etc/bash_completion.d/caddy
Zsh:

  # If shell completion is not already enabled in your environment,

  # you will need to enable it.  You can execute the following once:

  $ echo "autoload -U compinit; compinit" >> ~/.zshrc

  # To load completions for each session, execute once:

  $ caddy completion zsh > "${fpath[1]}/_caddy"

  # You will need to start a new shell for this setup to take effect.
fish:

  $ caddy completion fish | source

  # To load completions for each session, execute once:

  $ caddy completion fish > ~/.config/fish/completions/caddy.fish
PowerShell:

  PS> caddy completion powershell | Out-String | Invoke-Expression

  # To load completions for every new session, run:

  PS> caddy completion powershell > caddy.ps1

  # and source this file from your PowerShell profile.
```

## OPTIONS
-h, --help[=false] help for completion

## SEE ALSO
caddy(8)

## HISTORY
2-Jul-2026 Auto generated by spf13/cobra


caddy-environ

title: caddy-environ(8)

text:
# caddy-environ(8)

## NAME
caddy-environ - Prints the environment

## SYNOPSIS
caddy environ [--envfile ] [flags]

## DESCRIPTION
Prints the environment as seen by this Caddy process.

The environment includes variables set in the system. If your Caddy configuration uses environment variables (e.g. "{env.VARIABLE}") then this command can be useful for verifying that the variables will have the values you expect in your config.

If --envfile is specified, an environment file with environment variables in the KEY=VALUE format will be loaded into the Caddy process.

Note that environments may be different depending on how you run Caddy. Environments for Caddy instances started by service managers such as systemd are often different than the environment inherited from your shell or terminal.

You can also print the environment the same time you use "caddy run" by adding the "--environ" flag.

Environments may contain sensitive data.

## OPTIONS
--envfile=[] Environment file(s) to load

-h, --help[=false] help for environ

## SEE ALSO
caddy(8)

## HISTORY
2-Jul-2026 Auto generated by spf13/cobra