darkstat

package: darkstat

title: darkstat(8)

summary: network statistics gatherer

text:
# darkstat(8)

## NAME
darkstat - network statistics gatherer

## SYNOPSIS
darkstat [ -i interface ] [ -r file ] [ --snaplen bytes ] [ --pppoe ] [ --syslog ] [ --verbose ] [ --no-daemon ] [ --no-promisc ] [ --no-dns ] [ --no-macs ] [ --no-lastseen ] [ -p port ] [ -b bindaddr ] [ --base path ] [ -f filter ] [ -l network/netmask ] [ --local-only ] [ --chroot dir ] [ --user username ] [ --daylog filename ] [ --import filename ] [ --export filename ] [ --pidfile filename ] [ --hosts-max count ] [ --hosts-keep count ] [ --ports-max count ] [ --ports-keep count ] [ --highest-port port ] [ --wait secs ] [ --hexdump ]

## DESCRIPTION
darkstat is a packet sniffer that runs as a background process, gathers all sorts of statistics about network usage, and serves them over HTTP.

All settings are passed on the commandline.

## OPTIONS
-i interface

Capture traffic on the specified network interface. This is the only mandatory commandline argument.

-r file

Instead of capturing live traffic, read it from a pcap(3) capture file. This is only useful for development and benchmarking. The -r and -i arguments are mutually exclusive.

--snaplen bytes

How many bytes to capture from the start of each packet. You should not need to specify this; darkstat will calculate it automatically.

--pppoe

Don't use this. Instead, capture on the tunnel interface that your PPPoE software provides, for example tun0 on FreeBSD, pppoe0 on OpenBSD or NetBSD.

If you really must, you can capture on an Ethernet interface and pass this argument to have darkstat decode PPPoE frames and ignore everything else. Make sure you also specify your local address with the -l argument!

--syslog

Errors, warnings, and verbose messages will go to syslog (facility daemon, priority debug) instead of stderr. On some systems, these messages end up in /var/log/debug by default.

--verbose

Produce more verbose debugging messages.

--no-daemon

Do not detach from the controlling terminal; stay in the foreground.

--no-promisc

Do not use promiscuous mode to capture. Note that an interface may already be in promiscuous mode, or may later enter promiscuous mode, due to circumstances beyond darkstat's control. If this is a problem, use -f to specify an appropriate bpf(4) filter.

--no-dns

Do not resolve IPs to host names. This can significantly reduce memory footprint on small systems as an extra process is created for DNS resolution.

--no-macs

Do not display MAC addresses in the hosts table.

--no-lastseen

Do not display the last seen time in the hosts table.

-p port

Bind the web interface to the specified port. The default is 667.

-b bindaddr

Bind the web interface to the specified address. The default is to listen on all interfaces.

--base path

Specify the path of the base URL. This can be useful if darkstat is accessed via a reverse proxy. For example, if you use Apache's mod_proxy and want to avoid a complicated setup with mod_proxy_html (and mod_header to unset the Accept-Encoding header), just set the base path to something like stats and use a config similar to the following snippet:

ProxyPass /stats/ http://localhost:667/stats/

ProxyPassReverse /stats/ http://localhost:667/stats/

The default is / (i.e. the root).

-f filter

Use the specified filter expression when capturing traffic. The filter syntax is beyond the scope of this manual page; please refer to the tcpdump(1) documentation.

-l network/netmask

Define a "local network" according to the network and netmask addresses. All traffic entering or leaving this network will be graphed, as opposed to the default behaviour of only graphing traffic to and from the local host.

The rule is that if ip_addr & netmask == network, then that address is considered local. See the usage example below.

--local-only

Make the web interface only display hosts on the "local network." This is intended to be used together with the -l argument.

--chroot dir

Force darkstat to chroot() into the specified directory. Without this argument, a default directory will be used, which is determined at build time. Usually /var/empty or /var/lib/empty.

For security reasons, this directory should be empty, and the user that darkstat is running as should not have write access to it.

However, if you wish to use --daylog or --export, darkstat will need write access to the chroot. If you are uncomfortable with the security implications, don't use any functionality that requires write access.

--user username

Force darkstat to drop privileges to the uid and gid of the specified user. Without this argument, a default value will be used, which is set at build time. Usually nobody.

For security reasons, this should not be root.

--daylog filename

Log daily traffic statistics into the named file, relative to the chroot directory. If you wish to use --daylog, you must first specify a --chroot directory, and it must be writeable by the darkstat user. A writeable chroot has security implications; if you are uncomfortable with this, do not use the --daylog functionality. If the daylog argument is not specified, no logging is performed.

The daylog format is:

localtime|time_t|bytes_in|bytes_out|pkts_in|pkts_outs

Lines starting with a # are comments stating when logging started and stopped.

--import filename

Upon starting, import a darkstat database from the named file, relative to the chroot directory. If you wish to use --import, you must first specify a --chroot directory. If the import is unsuccessful, darkstat will start with an empty database.

--export filename

On shutdown, or upon receiving SIGUSR1 or SIGUSR2, export the in-memory database to the named file, relative to the chroot directory. If you wish to use --export, you must first specify a --chroot directory, and it must be writeable by the darkstat user. A writeable chroot has security implications - if you are uncomfortable with this, do not use the --export functionality.

--pidfile filename

Creates a file containing the process ID of darkstat. This file will be unlinked upon clean shutdown. As with all pidfiles, if darkstat dies uncleanly, a stale pidfile can be left over. For example, start darkstat with:

darkstat -i fxp0 --chroot /var/run/darkstat --pidfile darkstat.pid

And stop with:

kill `cat /var/run/darkstat/darkstat.pid`

By default, kill(1) will send SIGTERM, which will cause darkstat to shut down cleanly.

--hosts-max count

The maximum number of hosts that will be kept in the hosts table. This is used to limit how much accounting data will be kept in memory. The number of --hosts-max must be greater than --hosts-keep

--hosts-keep count

When the hosts table hits --hosts-max and traffic is seen from a new host, we clean out the hosts table, keeping only the top --hosts-keep number of hosts, sorted by total traffic.

--ports-max count

The maximum number of ports that will be tracked for each host. This is used to limit how much accounting data will be kept in memory. The number of --ports-max must be greater than --ports-keep

--ports-keep count

When a ports table fills up, this many ports are kept and the rest are discarded.

--highest-port port

Ports that are numerically higher than this will not appear in the per-host ports tables, although their traffic will still be accounted for. This can be used to hide ephemeral ports. By default, all ports are tracked.

--wait secs

Don't use this. It's a hack to help victims of NetworkManager and similar systems.

You should start darkstat after the capture interface has come up. If you can't, specifying the --wait option will make darkstat sleep up to the specified number of seconds for the interface to become ready. Zero means wait indefinitely.

--hexdump

Show hex dumps of received traffic. This is only for debugging, and implies --verbose and --no-daemon.

## USAGE EXAMPLES
To gather statistics on the fxp0 interface:

darkstat -i fxp0

We want to account for traffic on the Internet-facing interface, but only serve web pages to our private local network where we have the IP address 192.168.0.1:

darkstat -i fxp0 -b 192.168.0.1

We want to serve web pages on the standard HTTP port:

darkstat -i fxp0 -p 80

We are on Optus (cable) and don't want to account for the constant ARP traffic we are receiving:

darkstat -i fxp0 -f "not arp"

We only want to account for SSH traffic:

darkstat -i fxp0 -f "port 22"

We don't want to account for traffic between internal IPs:

darkstat -i fxp0 -f "not (src net 192.168.0 and dst net 192.168.0)"

(For a full reference on filter syntax, refer to the tcpdump(1) manpage)

We have a network consisting of a gateway server (192.168.1.1) and a few workstations (192.168.1.2, 192.168.1.3, etc.) and we want to graph all traffic entering and leaving the local network, not just the gateway server (which is running darkstat):

darkstat -i fxp0 -l 192.168.1.0/255.255.255.0

On some systems, we can't capture on a "decoded" interface but only on nas0 which returns PPPoE encapsulated packets. Do PPPoE decoding, and override the local IP manually since it cannot be automatically detected. Note the /32 netmask:

darkstat -i nas0 --pppoe -l 192.168.1.1/255.255.255.255

## SIGNALS
To shut darkstat down cleanly, send a SIGTERM or SIGINT signal to the darkstat parent process.

Sending the SIGUSR1 signal will cause darkstat to empty out its in-memory database. If an --export file was set, it will first save the database to file. Sending SIGUSR2 will save the database without emptying it.

## FREQUENTLY ASKED QUESTIONS

### How many bytes does each bar on the graph represent?
Hover your mouse cursor over a bar and you should get a tooltip saying exactly how many bytes in and out the bar represents.

### Why aren't there labels / tics / a scale on the graphs?
Because implementing them is hard. And doing so correctly, and in a way that works across all browsers, looks pretty much impossible.

I might attempt it some day. In the meantime, patches would be gladly accepted.

### Why are the graphs blank? All the bars are zero.
The graphs only show traffic in/out of the local host, which is determined by getting the IP address of the interface you're sniffing on.

You can use the -l argument to override the local address for accounting purposes. You can also use it to do accounting for a whole subnet by specifying an appropriate netmask.

## SEE ALSO
tcpdump(1)

## HISTORY
darkstat was written in 2001, largely as a result of a certain Australian cable Internet provider introducing a 3GB monthly traffic limit.

## AUTHORS
Emil Mikulic and others. (see the AUTHORS file)

## WEBSITE
https://unix4lyfe.org/darkstat/


mount.davfs

title: mount.davfs(8)

text:
# mount.davfs(8)

## NAME
mount.davfs - Mount a WebDAV resource as davfs2 file system

## SYNOPSIS
mount.davfs [-h | --help] [-V | --version]

mount {dir | webdavserver}

## SYNOPSIS (root only)
mount -t davfs [-o option[,...]] webdavserver dir

mount.davfs [-o option[,...]] webdavserver dir

## DESCRIPTION
mount.davfs allows you to mount the WebDAV resource identified by webdavserver into the local filesystem at dir. WebDAV is an extension to HTTP that allows remote, collaborative authoring of Web resources, defined in RFC 4918. mount.davfs is part of davfs2.

davfs2 allows documents on a remote Web server to be edited using standard applications. For example, a remote Web site could be updated in-place using the same development tools that initially created the site. Or you may use a WebDAV resource for documents you want to access and edited from different locations.

davfs2 supports TLS/SSL (if the neon library supports it) and proxies. mount.davfs runs as a daemon in userspace. It integrates into the virtual file system by the fuse kernel files system. Currently FUSE_KERNEL_VERSION 7 is supported.

mount.davfs is usually invoked by the mount(8) command when using the -t davfs option. After mounting it runs as a daemon. To unmount the umount(8) command is used.

webdavserver is the URL of the server. It must at least contain the host name. It may additionally contain the scheme, the port and the path. Missing components are set to sensible default values. The path component must not be %-encoded, but when entering the URL at the command line or in /etc/fstab the escaping rules of the shell or fstab must be obeyed.

dir is the mountpoint where the WebDAV resource is mounted on. It may be an absolute or relative path.

fstab may be used to define mounts and mount options as usual. In place of the device the url of the WebDAV server must be given. There must not be more than one entry in fstab for every mountpoint.

## OPTIONS
-V --version

Output version.

-h --help

Print a help message.

-o

A comma-separated list defines mount options to be used. Available options are:

[no]auto

Can (not) be mounted with mount -a.

Default: auto.

comment=some comment

This option is ignored by mount.davfs but other programs may require it to be present in fstab.

conf=absolute path

An alternative user configuration file. This option is intended for cases where the default user configuration file in the users home directory can not be used.

Default: ~/.davfs2/davfs2.conf

[no]dev

(Do not) interpret character or block special devices on the file system. This option is only included for compatibility with the mount(8) program. It will always be set to nodev

dir_mode=mode

The default mode bits for directories in the mounted file system. Value given in octal. s-bits for user and group are always silently ignored.

Default: calculated from the umask of the mounting user; an x-bit is associated to every r-bit in u-g-o.

[no]exec

(Do not) allow execution of any binaries on the mounted file system.

Default: exec. (When mounting as an ordinary user, the mount(8) program will set the default to noexec.)

file_mode=mode

The default mode bits for files in the mounted file system. Value given in octal. s-bits for user and group are always silently ignored.

Default: calculated from the umask of the mounting user; no x-bits are set for files.

gid=group

The group the mounted file system belongs to. It may be a numeric ID or a group name. The mounting user, if not root, must be member of this group.

Default: the primary group of the mounting user.

[no]grpid

When this option is set a newly created file will take the group id of the directory in which it is created. This will also apply to all files that are on the server and not in the local cache. (That is because the group id is not stored on the server.)

If the group id of the directory is root this option is ignored.

Default: nogrpid.

[no]_netdev

The file system needs a (no) network connection for operation. This information allows the operating system to handle the file system properly at system start and when the network is shut down.

Default: _netdev

ro

Mount the file system read-only.

Default: rw.

rw

Mount the file system read-write.

Default: rw.

[no]suid

Do not allow set-user-identifier or set-group-identifier bits to take effect. This option is only included for compatibility with the mount program. It will always be set to nosuid.

[no]user

(Do not) allow an ordinary user to mount the file system. The name of the mounting user is written to mtab so that he can unmount the file system again. Option user implies the options noexec, nosuid and nodev (unless overridden by subsequent options). This option makes only sense when set in fstab.

Default: ordinary users are not allowed to mount.

users

Like user, but any user is allowed to unmount the file system, not only the mounting user. This is generally not recomended. If the user option allows an unprivileged user to mount, but unmounting by the mounting user fails the users may be a work around.

Default: only the mounting user is allowed to unmount the file system.

uid=user

The owner of the mounted file system. It may be a numeric ID or a user name. Only when mounted by root, this may be different from the mounting user.

Default: ID of the mounting user.

username=WebDAV_user

Use this name to authenticate with the WebDAV server. This option is intended for use with pam_mount only. When this option is set the credentials in the secrets files will be ignored. The password will always be read from stdin, even when option askauth is set to 0. Do not use it in fstab. The username will be visible for everyone in the output of ps.

Default: no username.

## SECURITY POLICY
mount.davfs needs root privileges for mounting. But running a daemon, that is connected to the internet, with root privileges is a security risk. So mount.davfs will change its uid and gid when entering daemon mode.

When invoked by root mount.davfs will run as user davfs2 and group davfs2. This may be changed in /etc/davfs2/davfs2.conf.

When invoked by an ordinary user it will run with the id of this user and with group davfs2.

As the file system may be mounted over an insecure internet connection, this increases the risk that malicious content may be included in the file system. So mount.davfs is slightly more restrictive than mount(8).

Options nosuid and nodev will always be set; even root can not change this.

For ordinary users to be able to mount, they must be member of group davfs2 and there must be an entry in fstab.

When the mount point given in fstab is a relative file name and the file system is mounted by an unprivileged user, the mount point must lie within the home directory of the mounting user.

If in fstab option uid and/or gid are given, an ordinary user can only mount, if her uid is the one given in option uid and he belongs to the group given in option gid.

WARNING: If root allows an ordinary user to mount a file system (using fstab) this includes the permission to read the associated credentials from /etc/davfs2/secrets as well as the private key of the associated client certificate and the mounting user may get access to this information. You should only do this, if you might as well give this information to the user directly.

## URLS AND MOUNT POINTS WITH SPACES
Special characters like spaces in pathnames are a mess. They are interpreted differently by different programs and protocols, and there are different rules for escaping.

In fstab spaces must be replaced by a three digit octal escape sequence. Write http://foo.bar/path\040with\040spaces instead of http://foo.bar/path with spaces.

For the davfs2.conf and the secrets files please see the escape and quotation rules described in the davfs2.conf(5) man page.

On command line you must obey the escaping rules of the shell.

## CACHING
mount.davfs tries to reduce HTTP-trafic by caching and reusing data. Information about directories and files are held in memory, while downloaded files are cached on disk.

mount.davfs needs to hold a local copy of all open files in the cache directory. Please make sure that enough local disk space is available.

mount.davfs will consider cached information about directories and file attributes valid for a configurable time and look up this information on the server only after this time has expired (or there is other evidence that this information is stale). So if somebody else creates or deletes files on the server it may take some time before the local file system reflects this.

This will not affect the content of files and directory listings. Whenever a file is opened, the server is looked up for a newer version of the file. Please consult the manual davfs2.conf(5) to see how can you configure this according your needs.

## LOCKS, LOST UPDATE PROBLEM AND BACKUP FILES
WebDAV introduced locks and mount.davfs uses them by default. This will in most cases prevent two people from changing the same file in parallel. But not always:

You might have disabled locks in /etc/davfs2/davfs2.conf or ~/.davfs2/davfs2.conf.

The server might not support locks (they are not mandatory).

A bad connection might prevent mount.davfs from refreshing the lock in time.

Another WebDAV-client might use your lock (that is not too difficult and might even happen without intention).

mount.davfs will therefore check if the file has been changed on the the server before it uploads a new version. If it finds it impossible to upload the locally changed file, it will store it in the local backup direcotry lost+found. You should check this directory from time to time and decide what to do with this files.

Sometimes locks held by some client on the server will not be released. Maybe the client crashes or the network connection fails. When mount.davfs finds a file locked on the server, it will check whether the lock is held by mount.davfs and the current user, and if so tries to reuse and release it. But this will not always succeed. So servers should automatically release locks after some time, when they are not refreshed by the client.

WebDAV allows one to lock files that don't exist (to protect the name when a client intends to create a new file). This locks will be displayed as files with size 0 and last modified date of 1970-01-01. If this locks are not released properly mount.davfs may not be able to access this files. You can use cadaver(1) <http://www.webdav.org/cadaver/> to remove this locks.

## FILE OWNER AND PERMISSIONS
davfs2 implements Unix permissions for access control. But changing owner and permissions of a file is only local. It is intended as a means for the owner of the file system, to control whether other local users may acces this file system.

The server does not know about this. From the servers point of view there is just one user (identified by the credentials) connected. Another WebDAV-client, connected to the same server, is not affected by this local changes.

There is one exception: The execute bit on files is stored as a property on the sever. You may think of this property as an information about the type of file rather than a permission. Whether the file is executable on the local system is still controlled by mount options and local permissions.

When the file system is unmounted, attributes of cached files (including owner and permissions) are stored in cache, as well as the attributs of the direcotries they are in. But there is no information stored about directories that do not contain cached files.

## FILES
/etc/davfs2/davfs2.conf

System wide configuration file.

~/.davfs2/davfs2.conf

Configuration file in the users home directory.The user configuration takes precedence over the system wide configuration. If it does not exist, mount.davfs will will create a template file.

/etc/davfs2/secrets

Holds the credentials for WebDAV servers and the proxy, as well as decryption passwords for client certificates. The file must be read-writable by root only.

~/.davfs2/secrets

Holds credentials for WebDAV servers and proxy, as well as decryption passwords for client certificates. The file must be read-writable by the owner only. Credentials are first looked up in the home directory of the mounting user. If not found there the system wide secrets file is consulted. If no creditentials and passwords are found they are asked from the user interactively (if not disabled). If the file does not exist, mount.davfs will will create a template file.

/etc/davfs2/certs

You may store trusted server certificates here, that can not be verified by use of the system wide CA-Certificates. This is useful when your server uses a selfmade certificate. You must configure the servercert option in /etc/davfs2/davfs2.conf or ~/.davfs2/davfs2.conf to use it. Certificates must be in PEM format.

Be sure to verify the certificate.

~/.davfs2/certs

You may store trusted server certificates here, that can not be verified by use of the system wide CA-Certificates. This is useful when your server uses a selfmade certificate. You must configure the servercert option in ~/.davfs2/davfs2.conf to use it. Certificates must be in PEM format.

Be sure to verify the certificate.

/etc/davfs2/certs/private

To store client certificates. Certificates must be in PKCS#12 format. You must configure the clientcert option in /etc/davfs2/davfs2.conf or ~/.davfs2/davfs2.conf to use it. This directory must be rwx by root only.

~/.davfs2/certs/private

To store client certificates. Certificates must be in PKCS#12 format. You must configure the clientcert option in ~/.davfs2/davfs2.conf to use it. This directory must be rwx by the owner only.

/var/run/mount.davfs

PID-files of running mount.davfs processes are stored there. This directory must belong to group davfs2 with write permissions for the group and the sticky-bit set (mode 1775). The PID-files are named after the mount point of the file system.

/var/cache/davfs2

System wide directory for cached files. Used when the file system is mounted by root. It must belong do group davfs2 and read, write and execute bits for group must be set. There is a subdirectory for every mounted file system. The names of this subdirectories are created from url, mount point and user name.

~/.davfs2/cache

Cache directory in the mounting users home directory. For every mounted WebDAV resource a subdirectory is created.

mount.davfs will try to create missing directories, but it will not touch /etc/davfs2.

## ENVIRONMENT
https_proxy http_proxy all_proxy

If no proxy is defined in the configuration file the value is taken from this environment variables. The proxy may be given with or without scheme and with or without port

http_proxy=[http://]foo.bar[:3218]

Only used when the mounting user is root.

no_proxy

A comma separated list of domain names that shall be accessed directly. * matches any domain name. A domain name starting with . (period) matches all subdomains.

Only used when the mounting user is root.

Not applied when the proxy is defined in /etc/davfs2.

## EXAMPLES
Non root user (e.g. filomena):

To allow an ordinary user to mount there must be an entry in fstab

http://webdav.org/dav /media/dav davfs noauto,user 0 0

If a proxy must be used this should be configured in /etc/davfs2/davfs2.conf

proxy proxy.mycompany.com:8080

Credentials are stored in /home/filomena/.davfs2/secrets

proxy.mycompany.com filomena "my secret"

/media/dav webdav-username password

If you have two-factor authentication enabled and if you can provide the token together with the password in the form of password:token, then add the string '2FA' as the forth parameter and you will be asked for token during mounting.

/media/dav user-name "p@ss\"w0rd" 2FA

Now the WebDAV resource may be mounted by user filomena invoking

mount /media/dav

and unmounted by user filomena invoking

umount /media/dav

Root user only:

Mounts the resource https://asciigirl.com/webdav at mount point /mount/site, encrypting all traffic with SSL. Credentials for http://webdav.org/dav will be looked up in /etc/davfs2/secrets, if not found there the user will be asked.

mount -t davfs -o uid=otto,gid=users,mode=775 https://asciigirl.com/webdav /mount/site

Mounts the resource http://linux.org.ar/repos at /dav.

mount.davfs -o uid=otto,gid=users,mode=775 http://linux.org.ar/repos/ /dav

## BUGS
davfs2 does not support links.

A davfs2 file system cannot be moved with mount --move.

## AUTHORS
This man page was written by Luciano Bello <luciano@linux.org.ar> for Debian, for version 0.2.3 of davfs2.

It has been updated for this version by Werner Baumann <werner.baumann@onlinhome.de>.

davfs2 is developed by Sung Kim <hunkim@gmail.com>.

Version 1.0.0 (and later) of davfs2 is a complete rewrite by Werner Baumann.

## DAVFS2 HOME
https://github.com/alisarctl/davfs2

## SEE ALSO
umount.davfs(8), davfs2.conf(5), mount(8), umount(8), fstab(5)


umount.davfs

title: umount.davfs(8)

text:
# umount.davfs(8)

## NAME
umount.davfs - Umount-helper to unmount a davfs2 file system

## SYNOPSIS
umount.davfs [-h | --help] [-V | --version]

umount dir

## SYNOPSIS (root only)
umount.davfs dir

## DESCRIPTION
umount.davfs is a umount helper program. It is called by the umount(8) command. Its purpose is to prevent the umount command from returning unless mount.davfs has synchronized all its cached files with the webdav server.

dir is the mountpoint where the WebDAV resource is mounted on. It may be an absolute or relative path.

While for local file systems umount(8) will only return when all cached data have been written to disk, this is not automatically true for a mounted davfs2 file system. With this umount helper the user can rely on the familiar behaviour of umount(8). To inform the operating system that the file system uses a network connection, you should always use the _netdev option, when mounting as davfs2 file system.

Depending on the amount of data and the quality of the connection, unmounting a davfs2 file system may take some seconds up to some hours.

If the mount.davfs daemon encountered serious errors, umount.davfs may return an error instead of unmounting the file system. In this case try umount -i. The -i option will prevent umount(8) from calling umount.davfs.

## OPTIONS
-V --version

Output version.

-h --help

Print a help message.

-f -l -n -r -v -t

This options are ignored. They are only recognized for compatibility with umount(8).

## FILES
/var/run/mount.davfs

PID-files of running umount.davfs processes are looked up here.

## BUGS
No known bugs.

## AUTHORS
This man page was written by Werner Baumann <werner.baumann@onlinehome.de>.

## DAVFS2 HOME
https://github.com/alisarctl/davfs2

## SEE ALSO
mount.davfs(8), umount(8), davfs2.conf(5), fstab(5)


debootstrap

package: debootstrap

title: debootstrap(8)

summary: Bootstrap a basic Debian system

text:
# debootstrap(8)

## NAME
debootstrap - Bootstrap a basic Debian system

## SYNOPSIS
debootstrap [OPTION...] SUITE TARGET [MIRROR [SCRIPT]]

debootstrap [OPTION...] --second-stage

## DESCRIPTION
debootstrap bootstraps a basic Debian system of SUITE into TARGET from MIRROR by running SCRIPT. MIRROR can be an http:// or https:// URL, a file:/// URL, or an ssh:/// URL.

The SUITE may be a release code name (eg, sid, stretch, jessie) or a symbolic name (eg, unstable, testing, stable, oldstable)

Notice that file:/ URLs are translated to file:/// (correct scheme as described in RFC1738 for local filenames), and file:// will not work. ssh://USER@HOST/PATH URLs are retrieved using scp; use of ssh-agent or similar is strongly recommended.

Debootstrap can be used to install Debian in a system without using an installation disk but can also be used to run a different Debian flavor in a chroot environment. This way you can create a full (minimal) Debian installation which can be used for testing purposes (see the EXAMPLES section). If you are looking for a chroot system to build packages please take a look at pbuilder.

## OPTIONS
--arch=ARCH

Set the target architecture (use if dpkg isn't installed). See also --foreign.

--include=alpha,beta

Comma separated list of packages which will be added to download and extract lists.

--exclude=alpha,beta

Comma separated list of packages which will be removed from download and extract lists. WARNING: you can and probably will exclude essential packages, be careful using this option.

--extra-suites=alpha,beta

Also use packages from the listed suites of the archive.

--components=alpha,beta

Use packages from the listed components of the archive.

--no-resolve-deps

By default, debootstrap will attempt to automatically resolve any missing dependencies, warning if any are found. Note that this is not a complete dependency resolve in the sense of dpkg or apt, and that it is far better to specify the entire base system than rely on this option. With this option set, this behaviour is disabled.

--log-extra-deps

If you want to record additional dependencies when resolving package dependencies, set this option to track them through debootstrap.log.

--variant=minbase|buildd|fakechroot

Name of the bootstrap script variant to use. Currently, the variants supported are minbase, which only includes required packages and apt; buildd, which installs the build-essential packages and fakechroot, which installs the packages without root privileges. The default, with no --variant=X argument, is to create a base Debian installation with all packages of priority required and important, including apt.

--merged-usr

Create /{bin,sbin,lib}/ symlinks pointing to their counterparts in /usr/. (Default for most variants and suites.)

--no-merged-usr

Do not create /{bin,sbin,lib}/ symlinks pointing to their counterparts in /usr/. (Default for the buildd variant of Debian 12 'bookworm' or older, and all variants of Debian 9 'stretch' or older.)

--keyring=KEYRING

Override the default keyring for the distribution being bootstrapped, and use KEYRING to check signatures of retrieved Release files.

--no-check-gpg

Disables checking gpg signatures of retrieved Release files.

--force-check-gpg

Forces checking Release file signatures, disabling automatic fallback to HTTPS in case of a missing keyring. Incompatible with the previous option.

--verbose

Produce more info about downloading.

--print-debs

Print the packages to be installed, and exit. Note that an empty or non-existing TARGET directory must be specified so that debootstrap can download Packages files to determine which packages should be installed, and to resolve dependencies. The TARGET directory will be deleted unless --keep-debootstrap-dir is specified.

--download-only

Download packages, but don't perform installation.

--foreign

Do the initial unpack phase of bootstrapping only, for example if the target architecture does not match the host architecture. A copy of debootstrap sufficient for completing the bootstrap process will be installed as /debootstrap/debootstrap in the target filesystem. You can run it with the --second-stage option to complete the bootstrapping process.

--second-stage

Complete the bootstrapping process. Other arguments are generally not needed.

--second-stage-target=DIR

Run second stage in a subdirectory instead of root. (can be used to create a foreign chroot) (requires --second-stage)

--keep-debootstrap-dir

Don't delete the /debootstrap directory in the target after completing the installation.

--cache-dir=DIR

Cache .deb files under directory. It should be an absolute path.

--unpack-tarball=FILE

Acquire .debs from gzipped tarball FILE (specified with absolute path) instead of downloading via HTTP(S).

--make-tarball=FILE

Instead of bootstrapping, make a gzipped tarball (written to FILE) of the downloaded packages. The resulting tarball may be passed to a later --unpack-tarball. Note that an empty or non-existing TARGET directory must be specified so that debootstrap can download packages to prepare the tarball. The TARGET directory will be deleted unless --keep-debootstrap-dir is specified.

--debian-installer

Used for internal purposes by the debian-installer

--extractor=TYPE

Override automatic .deb extractor selection to TYPE. Supported extractors are: dpkg-deb and ar.

--no-check-certificate

Do not check certificate against certificate authorities

--certificate=FILE

Use the client certificate stored in file (PEM)

--private-key=FILE

Read the private key from file

--inrelease-path

Determine the path to the InRelease file of the suite relative to the normal position of an InRelease file

## EXAMPLES
To setup a stretch system:

debootstrap stretch ./stretch-chroot http://deb.debian.org/debian

debootstrap stretch ./stretch-chroot file:///LOCAL_MIRROR/debian

Full process to create a complete Debian installation of sid (unstable) in a chroot:

main # debootstrap sid sid-root http://deb.debian.org/debian/

[ ... watch it download the whole system ]

main # echo "proc sid-root/proc proc defaults 0 0" >> /etc/fstab

main # mount proc sid-root/proc -t proc

main # echo "sysfs sid-root/sys sysfs defaults 0 0" >> /etc/fstab

main # mount sysfs sid-root/sys -t sysfs

main # cp /etc/hosts sid-root/etc/hosts

main # chroot sid-root /bin/bash

## AUTHOR
debootstrap was written by Anthony Towns <ajt@debian.org>. This manpage was written by Matt Kraai <kraai@debian.org>.


debuginfod

package: debuginfod

title: debuginfod(8)

text:
# debuginfod(8)

## NAME
debuginfod - debuginfo-related http file-server daemon

## SYNOPSIS
debuginfod [OPTION]... [PATH]...

## DESCRIPTION
debuginfod serves debuginfo-related artifacts over HTTP. It periodically scans a set of directories for ELF/DWARF files and their associated source code, as well as archive files containing the above, to build an index by their buildid. This index is used when remote clients use the HTTP webapi, to fetch these files by the same buildid.

If a debuginfod cannot service a given buildid artifact request itself, and it is configured with information about upstream debuginfod servers, it queries them for the same information, just as debuginfod-find would. If successful, it locally caches then relays the file content to the original requester.

Indexing the given PATHs proceeds using multiple threads. One thread periodically traverses all the given PATHs logically or physically (see the -L option). Duplicate PATHs are ignored. You may use a file name for a PATH, but source code indexing may be incomplete; prefer using a directory that contains the binaries. The traversal thread enumerates all matching files (see the -I and -X options) into a work queue. A collection of scanner threads (see the -c option) wait at the work queue to analyze files in parallel.

If the -F option is given, each file is scanned as an ELF/DWARF file. Source files are matched with DWARF files based on the AT_comp_dir (compilation directory) attributes inside it. Caution: source files listed in the DWARF may be a path anywhere in the file system, and debuginfod will readily serve their content on demand. (Imagine a doctored DWARF file that lists /etc/passwd as a source file.) If this is a concern, audit your binaries:

```
% eu-srcfiles -e BINARY
```

If any of the -R, -U, or -Z options is given, each file is scanned as an archive file that may contain ELF/DWARF/source files. Archive files are recognized by extension. If -R is given, ".rpm" files are scanned; if -U is given, ".deb" and ".ddeb" files are scanned; if -Z is given, the listed extensions are scanned.

Because of complications such as DWZ-compressed debuginfo, it may require two traversal passes to identify all source code. Source files for binaries in archives are only served from archives, so the caution for -F does not apply. If the same source file may be found in multiple different archives, a heuristic chooses the one closest to the archive holding the debuginfo. ("closest" means "longest common archive name prefix"). Note that due to Debian/Ubuntu packaging policies & mechanisms, debuginfod cannot resolve source files for DEB/DDEB at all. Consider using the --disable-source-scan option.

If no PATH is listed, or none of the scanning options is given, then debuginfod will simply serve content that it accumulated into its index in all previous runs, periodically groom the database, and federate to any upstream debuginfod servers. In passive mode, debuginfod will only serve content from a read-only index and federated upstream servers, but will not scan or groom.

## OPTIONS
-F

Activate ELF/DWARF file scanning. The default is off.

-Z EXT -Z EXT=CMD

Activate an additional pattern in archive scanning. Files with name extension EXT (include the dot) will be processed. If CMD is given, it is invoked with the file name added to its argument list, and should produce a common archive on its standard output. Otherwise, the file is read as if CMD were "cat". Since debuginfod internally uses libarchive to read archive files, it can accept a wide range of archive formats and compression modes. The default is no additional patterns. This option may be repeated.

-R

Activate RPM patterns in archive scanning. The default is off. Equivalent to -Z .rpm=cat, since libarchive can natively process RPM archives. If your version of libarchive is much older than 2020, be aware that some distributions have switched to an incompatible zstd compression for their payload. You may experiment with -Z .rpm='(rpm2cpio|zstdcat)<' instead of -R.

-U

Activate DEB/DDEB patterns in archive scanning. The default is off. Equivalent to -Z .deb='(bsdtar -O -x -f - data.tar\*)<' and same for .ddeb and .ipk.

-d FILE --database=FILE

Set the path of the sqlite database used to store the index. This file is disposable in the sense that a later rescan will repopulate data. It will contain absolute file path names, so it may not be portable across machines. It may be frequently read/written, so it should be on a fast filesystem. It should not be shared across machines or users, to maximize sqlite locking performance. For quick testing the magic string ":memory:" can be used to use an one-time memory-only database. The default database file is $HOME/.debuginfod.sqlite.

--passive

Set the server to passive mode, where it only services webapi requests, including participating in federation. It performs no scanning, no grooming, and so only opens the sqlite database read-only. This way a database can be safely shared between a active scanner/groomer server and multiple passive ones, thereby sharing service load. Archive pattern options must still be given, so debuginfod can recognize file name extensions for unpacking.

-D SQL --ddl=SQL

Execute given sqlite statement after the database is opened and initialized as extra DDL (SQL data definition language). This may be useful to tune performance-related pragmas or indexes. May be repeated. The default is nothing extra.

-p NUM --port=NUM

Set the TCP port number (0 < NUM < 65536) on which debuginfod should listen, to service HTTP requests. Both IPv4 and IPV6 sockets are opened, if possible. The webapi is documented below. The default port number is 8002.

-I REGEX --include=REGEX -X REGEX --exclude=REGEX

Govern the inclusion and exclusion of file names under the search paths. The regular expressions are interpreted as unanchored POSIX extended REs, thus may include alternation. They are evaluated against the full path of each file, based on its realpath(3) canonicalization. By default, all files are included and none are excluded. A file that matches both include and exclude REGEX is excluded. (The contents of archive files are not subject to inclusion or exclusion filtering: they are all processed.) Only the last of each type of regular expression given is used.

-t SECONDS --rescan-time=SECONDS

Set the rescan time for the file and archive directories. This is the amount of time the traversal thread will wait after finishing a scan, before doing it again. A rescan for unchanged files is fast (because the index also stores the file mtimes). A time of zero is acceptable, and means that only one initial scan should performed. The default rescan time is 300 seconds. Receiving a SIGUSR1 signal triggers a new scan, independent of the rescan time (including if it was zero), interrupting a groom pass (if any).

-r

Apply the -I and -X during groom cycles, so that most content related to files excluded by the regexes are removed from the index. Not all content can be practically removed, so eventually a "-G" "maximal-groom" operation may be needed.

-g SECONDS --groom-time=SECONDS

Set the groom time for the index database. This is the amount of time the grooming thread will wait after finishing a grooming pass before doing it again. A groom operation quickly rescans all previously scanned files, only to see if they are still present and current, so it can deindex obsolete files. See also the DATA MANAGEMENT section. The default groom time is 86400 seconds (1 day). A time of zero is acceptable, and means that only one initial groom should be performed. Receiving a SIGUSR2 signal triggers a new grooming pass, independent of the groom time (including if it was zero), interrupting a rescan pass (if any)..

-G

Run an extraordinary maximal-grooming pass at debuginfod startup. This pass can take considerable time, because it tries to remove any debuginfo-unrelated content from the archive-related parts of the index. It should not be run if any recent archive-related indexing operations were aborted early. It can take considerable space, because it finishes up with an sqlite "vacuum" operation, which repacks the database file by triplicating it temporarily. The default is not to do maximal-grooming. See also the DATA MANAGEMENT section.

-c NUM --concurrency=NUM

Set the concurrency limit for the scanning queue threads, which work together to process archives & files located by the traversal thread. This important for controlling CPU-intensive operations like parsing an ELF file and especially decompressing archives. The default is related to the number of processors on the system and other constraints; the minimum is 1.

-C -C=NUM --connection-pool --connection-pool=NUM

Set the size of the pool of threads serving webapi queries. The following table summarizes the interpretaton of this option and its optional NUM parameter. no option, -C

use a fixed thread pool sized automatically

-C=NUM

use a fixed thread pool sized NUM, minimum 2

The first mode is a simple and safe configuration related to the number of processors and other constraints. The second mode is suitable for tuned load-limiting configurations facing unruly traffic.

-L

Traverse symbolic links encountered during traversal of the PATHs, including across devices - as in find -L. The default is to traverse the physical directory structure only, stay on the same device, and ignore symlinks - as in find -P -xdev. Caution: a loops in the symbolic directory tree might lead to infinite traversal.

--fdcache-mbs=MB

Configure limits on a cache that keeps recently extracted files from archives. Up to a total of MB megabytes will be kept extracted, in order to avoid having to decompress their archives over and over again. The default MB values depend on the concurrency of the system, and on the available disk space on the $TMPDIR or /tmp filesystem. (This is because that is where the most recently used extracted files are kept.) While previous versions used plain LRU, the cache now attempts to preserve more frequently & recently accessed files, and especially those that took a long time to extract (e.g., vdso.debug!), and penalizes large / old files.

--fdcache-prefetch=NUM

Up to NUM other files from an archive may be prefetched into the cache before they are even requested. If unspecified, these values depend on concurrency of the system and on the available disk space on the $TMPDIR. Allocating more will improve performance in environments where multiple different parts of several large archives are being accessed.

--fdcache-mintmp=NUM

Configure a disk space threshold for emergency flushing of the caches. The filesystem holding the caches is checked periodically. If the available space falls below the given percentage, the caches are flushed, and the fdcaches will stay disabled until the next groom cycle. This mechanism, along a few associated /metrics on the webapi, are intended to give an operator notice about storage scarcity - which can translate to RAM scarcity if the disk happens to be on a RAM virtual disk. The default threshold is 25%.

--forwarded-ttl-limit=NUM

Configure limits of X-Forwarded-For hops. if X-Forwarded-For exceeds N hops, it will not delegate a local lookup miss to upstream debuginfods. The default limit is 8.

--disable-source-scan

Disable scan of the dwarf source info of debuginfo sections. If a setup has no access to source code, the source info is not required.

--scan-checkpoint=NUM

Run a synchronized SQLITE WAL checkpoint operation after every NUM completed archive or file scans. This may slow down parallel scanning phase somewhat, but generate much smaller "-wal" temporary files on busy servers. The default is 256. Disabled if 0.

-v

Increase verbosity of logging to the standard error file descriptor. May be repeated to increase details. The default verbosity is 0.

## WEBAPI
debuginfod's webapi resembles ordinary file service, where a GET request with a path containing a known buildid results in a file. Unknown buildid / request combinations result in HTTP error codes. This file service resemblance is intentional, so that an installation can take advantage of standard HTTP management infrastructure.

For most queries, some custom http headers are added to the response, providing additional metadata about the buildid-related response. For example:

```
% debuginfod-find -v debuginfo /bin/ls |& grep -i x-debuginfo
x-debuginfod-size: 502024
x-debuginfod-archive: /mnt/fedora_koji_prod/koji/packages/coreutils/9.3/4.fc39/x86_64/coreutils-debuginfo-9.3-4.fc39.x86_64.rpm
x-debuginfod-file: /usr/lib/debug/usr/bin/ls-9.3-4.fc39.x86_64.debug
```

X-DEBUGINFOD-SIZE

The size of the file, in bytes. This may differ from the http Content-Length: field (if present), due to compression in transit.

X-DEBUGINFOD-FILE

The full path name of the file related to the given buildid.

X-DEBUGINFOD-ARCHIVE

The full path name of the archive that contained the above file, if any.

There are a handful of buildid-related requests. In each case, the buildid is encoded as a lowercase hexadecimal string. For example, for a program /bin/ls, look at the ELF note GNU_BUILD_ID:

```
% readelf -n /bin/ls | grep -A4 build.id
Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
Owner          Data size  Type
GNU                   20  GNU_BUILD_ID
Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
```

Then the hexadecimal BUILDID is simply:

```
8713b9c3fb8a720137a4a08b325905c7aaf8429d
```

### /buildid/BUILDID/debuginfo
If the given buildid is known to the server, this request will result in a binary object that contains the customary .*debug_* sections. This may be a split debuginfo file as created by strip, or it may be an original unstripped executable.

### /buildid/BUILDID/executable
If the given buildid is known to the server, this request will result in a binary object that contains the normal executable segments. This may be a executable stripped by strip, or it may be an original unstripped executable. ET_DYN shared libraries are considered to be a type of executable.

### /buildid/BUILDID/source/SOURCE/FILE
If the given buildid is known to the server, this request will result in a binary object that contains the source file mentioned. The path should be absolute. Relative path names commonly appear in the DWARF file's source directory, but these paths are relative to individual compilation unit AT_comp_dir paths, and yet an executable is made up of multiple CUs. Therefore, to disambiguate, debuginfod expects source queries to prefix relative path names with the CU compilation-directory, followed by a mandatory "/".

Note: the caller may or may not elide ../ or /./ or extraneous /// sorts of path components in the directory names. debuginfod accepts both forms. Specifically, debuginfod canonicalizes path names according to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any // to / in the path.

For example:

\#include <stdio.h>

/buildid/BUILDID/source/usr/include/stdio.h

/path/to/foo.c

/buildid/BUILDID/source/path/to/foo.c

AT_comp_dir=/zoo/

/buildid/BUILDID/source/zoo//../bar/foo.c

Note: the client should %-escape characters in /SOURCE/FILE that are not shown as "unreserved" in section 2.3 of RFC3986. Some characters that will be escaped include "+", "\", "$", "!", the 'space' character, and ";". RFC3986 includes a more comprehensive list of these characters.

### /buildid/BUILDID/section/SECTION
If the given buildid is known to the server, the server will attempt to extract the contents of an ELF/DWARF section named SECTION from the debuginfo file matching BUILDID. If the debuginfo file can't be found or the section has type SHT_NOBITS, then the server will attempt to extract the section from the executable matching BUILDID. If the section is successfully extracted then this request results in a binary object of the section's contents. Note that this result is the raw binary contents of the section, not an ELF file.

### /metrics
This endpoint returns a Prometheus formatted text/plain dump of a variety of statistics about the operation of the debuginfod server. The exact set of metrics and their meanings may change in future versions.

## DATA MANAGEMENT
debuginfod stores its index in an sqlite database in a densely packed set of interlinked tables. While the representation is as efficient as we have been able to make it, it still takes a considerable amount of data to record all debuginfo-related data of potentially a great many files. This section offers some advice about the implications.

As a general explanation for size, consider that debuginfod indexes ELF/DWARF files, it stores their names and referenced source file names, and buildids will be stored. When indexing archives, it stores every file name of or in an archive, every buildid, plus every source file name referenced from a DWARF file. (Indexing archives takes more space because the source files often reside in separate subpackages that may not be indexed at the same pass, so extra metadata has to be kept.)

Getting down to numbers, in the case of Fedora RPMs (essentially, gzip-compressed cpio files), the sqlite index database tends to be from 0.5% to 3% of their size. It's larger for binaries that are assembled out of a great many source files, or packages that carry much debuginfo-unrelated content. It may be even larger during the indexing phase due to temporary sqlite write-ahead-logging files; these are checkpointed (cleaned out and removed) at shutdown. It may be helpful to apply tight -I or -X regular-expression constraints to exclude files from scanning that you know have no debuginfo-relevant content.

As debuginfod runs in normal active mode, it periodically rescans its target directories, and any new content found is added to the database. Old content, such as data for files that have disappeared or that have been replaced with newer versions is removed at a periodic grooming pass. This means that the sqlite files grow fast during initial indexing, slowly during index rescans, and periodically shrink during grooming. There is also an optional one-shot maximal grooming pass is available. It removes information debuginfo-unrelated data from the archive content index such as file names found in archives ("archive sdef" records) that are not referred to as source files from any binaries find in archives ("archive sref" records). This can save considerable disk space. However, it is slow and temporarily requires up to twice the database size as free space. Worse: it may result in missing source-code info if the archive traversals were interrupted, so that not all source file references were known. Use it rarely to polish a complete index.

You should ensure that ample disk space remains available. (The flood of error messages on -ENOSPC is ugly and nagging. But, like for most other errors, debuginfod will resume when resources permit.) If necessary, debuginfod can be stopped, the database file moved or removed, and debuginfod restarted.

sqlite offers several performance-related options in the form of pragmas. Some may be useful to fine-tune the defaults plus the debuginfod extras. The -D option may be useful to tell debuginfod to execute the given bits of SQL after the basic schema creation commands. For example, the "synchronous", "cache_size", "auto_vacuum", "threads", "journal_mode" pragmas may be fun to tweak via -D, if you're searching for peak performance. The "optimize", "wal_checkpoint" pragmas may be useful to run periodically, outside debuginfod. The default settings are performance- rather than reliability-oriented, so a hardware crash might corrupt the database. In these cases, it may be necessary to manually delete the sqlite database and start over.

As debuginfod changes in the future, we may have no choice but to change the database schema in an incompatible manner. If this happens, new versions of debuginfod will issue SQL statements to drop all prior schema & data, and start over. So, disk space will not be wasted for retaining a no-longer-useable dataset.

In summary, if your system can bear a 0.5%-3% index-to-archive-dataset size ratio, and slow growth afterwards, you should not need to worry about disk space. If a system crash corrupts the database, or you want to force debuginfod to reset and start over, simply erase the sqlite file before restarting debuginfod.

In contrast, in passive mode, all scanning and grooming is disabled, and the index database remains read-only. This makes the database more suitable for sharing between servers or sites with simple one-way replication, and data management considerations are generally moot.

## SECURITY
debuginfod does not include any particular security features. While it is robust with respect to inputs, some abuse is possible. It forks a new thread for each incoming HTTP request, which could lead to a denial-of-service in terms of RAM, CPU, disk I/O, or network I/O. If this is a problem, users are advised to install debuginfod with a HTTPS reverse-proxy front-end that enforces site policies for firewalling, authentication, integrity, authorization, and load control.

Front-end proxies may elide sensitive path name components in X-DEBUGINFOD-FILE/ARCHIVE response headers. For example, using Apache httpd's mod_headers, you can remove the entire directory name prefix:

```
Header edit x-debuginfod-archive ".*/" ""
```

When relaying queries to upstream debuginfods, debuginfod does not include any particular security features. It trusts that the binaries returned by the debuginfods are accurate. Therefore, the list of servers should include only trustworthy ones. If accessed across HTTP rather than HTTPS, the network should be trustworthy. Authentication information through the internal libcurl library is not currently enabled.

See the file man7/debuginfod-client-config.7.

## ADDITIONAL FILES
$HOME/.debuginfod.sqlite

Default database file.

## SEE ALSO
debuginfod-find(1) sqlite3(1) https://prometheus.io/docs/instrumenting/exporters/


debuginfod.service

title: debuginfod.service(8)

text:
# debuginfod.service(8)

## NAME
debuginfod.service - debuginfo related information server for systemd

## SYNOPSIS
/usr/lib/systemd/system/debuginfod.service

## DESCRIPTION
debuginfod.service integrates the debuginfod daemon with systemd, serving debuginfo-related artifacts over HTTP. The data is stored in /var/cache/debuginfod/debuginfod.sqlite. Configure /etc/sysconfig/debuginfod to set the below environment variables as well as those listed in debuginfod(8).

## Environment variables
$DEBUGINFOD_PORT - Changes port of debuginfod service daemon.

$DEBUGINFOD_VERBOSE - Change verbosity of reporting in debuginfod service daemon log file.

$DEBUGINFOD_PATHS - Changes paths to scan for debuginfod service daemon.

## FILES
/usr/lib/systemd/system/debuginfod.service, /var/cache/debuginfod/debuginfod.sqlite /etc/sysconfig/debuginfod

## SEE ALSO
debuginfod(8), debuginfod-find(1), systemctl(1), systemd.service(5)


applydeltaiso

package: deltarpm

title: applydeltaiso(8)

text:
# applydeltaiso(8)

## NAME
applydeltaiso - reconstruct an iso from the old iso and the deltaiso

## SYNOPSIS
applydeltaiso oldiso deltaiso newiso

## DESCRIPTION
applydeltaiso applies a deltaiso to oldiso to re-create newiso.

When specifying oldiso, you can specify a device (such as /dev/dvd).

## SEE ALSO
makedeltaiso(8)

## AUTHOR
Michael Schroeder <mls@suse.de>


applydeltarpm

title: applydeltarpm(8)

summary: reconstruct an rpm from a deltarpm

text:
# applydeltarpm(8)

## NAME
applydeltarpm - reconstruct an rpm from a deltarpm

## SYNOPSIS
applydeltarpm [-v] [-p] [-r oldrpm] deltarpm newrpm

applydeltarpm -c|-C deltarpm

applydeltarpm [-c|-C] -s sequence

applydeltarpm -i deltarpm

## DESCRIPTION
applydeltarpm applies a binary delta to either an old rpm or to on-disk data to re-create a new rpm. The old rpm can be specified with the -r option, if no rpm name is provided on-disk data is used. You can use -p to make applydeltarpm print the percentage of completion, or -v to make it more verbose about its operation.

The second an third form can be used to check if the reconstruction is possible. It may fail if the on-disk data got changed (deltarpms are created in a way that config file changes do not matter) or the deltarpm does not match the rpm the delta was generated with. The -c option selects full (i.e. slow) on-disk checking, whereas -C only checks if the filesizes have not changed.

Instead of a full deltarpm a sequence id can be given with the -s sequence option. Such an id contains all the information that is needed to do reconstruction checking.

Finally information about a deltarpm can be printed with the -i option.

## MEMORY CONSIDERATIONS
applydeltarpm was written to work on systems with limited memory. It uses a paging algorithm to keep the size of in-core data low and not bring the system in an out-of-memory situation.

## EXIT STATUS
applydeltarpm returns 0 if the rpm could be recreated or the checking succeeded, it returns 1 and prints an error message to stderr if something failed.

## SEE ALSO
makedeltarpm(8), rpm(8)

## AUTHOR
Michael Schroeder <mls@suse.de>


combinedeltarpm

title: combinedeltarpm(8)

text:
# combinedeltarpm(8)

## NAME
combindeltarpm - combine multiple deltarpms to a single one

## SYNOPSIS
combinedeltarpm [-v] [-V version] [-z compression] [-S signaturerpm] olddeltarpms... newdeltarpm

## DESCRIPTION
combinedeltarpm creates a new deltarpm from multiple old ones. Applying the resulting deltarpm has the same effect as applying each of the old ones in the specified order. Use the -v option to make combinedeltarpm more verbose about its work.

combinedeltarpm normally produces a V3 format deltarpm, use the -V option to specify a different version if desired. The -z option can be used to specify a different compression method, the default is to use the same compression method as used in the last of the old deltarpms.

If you want to use a different header signature you can also specify a rpm with the -S option which will be used as signature reference. This feature can be used to if a deltarpm was made against an unsigned rpm which later got signed.

## MEMORY CONSIDERATIONS
The implementation of combinedeltarpm currently unpacks the add-blocks of the deltarpms in memory, thus it needs about twice the uncompressed payload size of the target rpm.

## SEE ALSO
makedeltarpm(8) applydeltarpm(8)

## AUTHOR
Michael Schroeder <mls@suse.de>


drpmsync

title: drpmsync(8)

summary: sync a file tree with deltarpms

text:
# drpmsync(8)

## NAME
drpmsync - sync a file tree with deltarpms

## SYNOPSIS
drpmsync [-c config] [source] dir

drpmsync [-s|-S] serverconfig

cgi-bin/drpmsync

## DESCRIPTION
Drpmsync keeps a local file system tree in sync with a remote one. Its intended use is to work with rpm trees; the deltarpm technology can only save bandwidth if rpms get transmitted. Please use the rsync program for normal file trees.

Drpmsync can run in two modes: as a client it connects to a server, receives a file list and brings the tree up to date, as a server it answers incoming requests and transmits files and rpms.

## CLIENT MODE
In this mode drpmsync updates the tree in dir. It opens the configuration file dir/drpmsync/config to get information about which server to use and other settings. You can specify a different configuration file with the -c option. The following settings are understood (the default for the boolean settings is false):

source: server1 server2...

This is a list of servers to connect to. Drpmsync advances through this list until a working server is found. If a source is specified on the command line it is used instead of the one from the configuration. The syntax for the server entries is "host[:port]/tree".

log: logfile

Specifies the name of a logfile. If the name does not start with a slash, dir/drpmsync/ is prepended to it.

generate_deltas: true|false

Controls whether drpmsync generates a delta if it receives a new version of a rpm and the server doesn't provide a delta. This is only useful if the local tree is also exported to other clients via a local drpmsync server.

generate_delta_compression: comp

This parameter is forwarded to the makedeltarpm program when creating deltas. An example would be gzip,gzip.

keep_deltas: true|false

Tell drpmsync to save received or freshly created deltas to the dir/drpmsync/delta directory. Automatically true if generate_deltas or keep_uncombined is set to true.

keep_uncombined: true|false

This tells drpmsync to request uncombined deltas from the server instead of a precombined single delta. This makes sense if you re-export the tree and want to maximize the number of versions your clients can update from.

always_get_rpm: true|false

Configures whether drpmsync should request that the full rpm is always sent along with the delta. Only makes sense if you have a fast network connection so that applydeltarpm takes longer than transmitting the ful rpm.

deltarpmpath: path

Sets the directory where drpmsync searches for the deltarpm programs. The default is to search the $PATH variable.

## SERVER MODE
Drpmsync can wither work as CGI script or as a standalone server. CGI script mode is automatically selected if the REQUEST_METHOD environment variable is set. In this mode drpmsync expects the DRPMSYNC_CONFIG environment variable to contain the path to a server config file. For apache you can set this with the SetEnv directive.

Standalone mode is selected with the -s or -S option. In this mode the server configuration must be specified as an argument to the drpmsync program. The -s option makes the drpmsync program background itself and exit right away, while -S keeps the server in the foreground.

The server configuration can contain the following settings:

allow: pattern1 pattern2...

deny: pattern1 pattern2...

This provides the access control for the server. pattern can either be a simple glob pattern (only * is supported) or it can be a full regular expression if it is written as /RE/. The regular expression is automatically anchored at the start and the end. Examples are 10.10.* or /10\.10\..*/ If either the numerical ip address or the domain name of the client matches any entry of the deny list, access is forbidden. Otherwise the allow list is searched for a match. If none is found, access is also denied. The default setting for both lists is empty, so you have to provide an allow list to allow access for the clients.

log: logfile

Specifies the path of a logfile.

no_combine: true|false

If this setting is true the server does not combine deltarpms. This increases to amount of data that has to be transferred but reduces the processor load on the server.

tree: external_path internal_path

This statements exports the tree located at internal_path to the clients as directory external_path. All of the above settings are saved as settings of this particular tree, so different trees can use different configurations. This also means that the configuration directives of a tree must be above the tree statement.

The following settings are global and only needed for standalone mode:

serverlog: logfile

Specifies the path of a logfile used for logging server events.

servername: hostname[:port]

The name of the server. If hostname is empty, the fully qualified domain name is used instead. The port defaults to port 80.

serveraddr: addr

This address is used for binding the server's socket. If not specified, connections can come from any interface.

serveruser: user

servergroup: group

Configures the user and group the servers swicthes to after binding the socket to the desired port. Examples are nobody or wwwrun.

maxclients: num

This settings limits the maximum number of concurrent connections to num. The default value is 10 connections.

deltarpmpath: path

Sets the directory where drpmsync searches for the deltarpm programs. The default is to search the $PATH variable.

## FILES
dir/drpmsync/deltas

directory used to store the deltas

dir/drpmsync/lock

lock used to serialize syncrpm calls

dir/drpmsync/wip

temporary storing space for the transmitted objects

dir/drpmsync/cache

md5sum cache to speed up the calculation of the tree state

dir/drpmsync/timstamp

contains the time of the last finished sync and the last time the remote tree state was requested.

## SEE ALSO
makedeltarpm(8), combinedeltarpm(8), applydeltarpm(8),

## AUTHOR
Michael Schroeder <mls@suse.de>


fragiso

title: fragiso(8)

text:
# fragiso(8)

## NAME
fragiso - split rpm packages from an iso and reassemble the iso later on

## SYNOPSIS
fragiso make iso fiso

fragiso list fiso

fragiso fill [-m] fiso iso

## DESCRIPTION
fragiso can be used to convert an iso file into a fragment file, which is a list describing all of the rpms on the iso and a data chunk containing everything but the rpms. It is used by drpmsync when an iso needs to be transferred. The idea is that often the rpms on the iso are already available on the destination host, so it saves bandwidth to first transfer the fragmented iso, copy the locally available rpms, transfer the unavailable rpms and reassemble the iso file.

fragiso make converts the iso into the fragment iso, fragiso list can be used to extract the rpm information. This information consists of the offset and length of all rpms and the lead/signature header md5sum plus the header/payload md5sum. To reassemble the iso one has to copy the rpms at the right offset into a new file and then use fragiso fill later on to provide all data not contained in the rpms. The -m option tells fragiso to print the resulting md5sum of the iso to stdout. It can be used for verification purposes.

## SEE ALSO
drpmsync(8)

## AUTHOR
Michael Schroeder <mls@suse.de>


makedeltaiso

title: makedeltaiso(8)

summary: create a deltaiso from two isos

text:
# makedeltaiso(8)

## NAME
makedeltaiso - create a deltaiso from two isos

## SYNOPSIS
makedeltaiso oldiso newiso deltaiso

## DESCRIPTION
makedeltaiso creates a deltaiso from two isos.

Do not specify a device (such as /dev/dvd) for either oldiso or newiso.

## SEE ALSO
applydeltaiso(8)

## AUTHOR
Michael Schroeder <mls@suse.de>


makedeltarpm

title: makedeltarpm(8)

summary: create a deltarpm from two rpms

text:
# makedeltarpm(8)

## NAME
makedeltarpm - create a deltarpm from two rpms

## SYNOPSIS
makedeltarpm [-v] [-V version] [-z compression] [-m mbytes] [-s seqfile] [-r] [-u] oldrpm newrpm deltarpm

makedeltarpm [-v] [-V version] [-z compression] [-s seqfile] [-u] -p oldrpmprint oldpatchrpm oldrpm newrpm deltarpm

## DESCRIPTION
makedeltarpm creates a deltarpm from two rpms. The deltarpm can later be used to recreate the new rpm from either filesystem data or the old rpm. Use the -v option to make makedeltarpm more verbose about its work (use it twice to make it even more verbose).

If you want to create a smaller and faster to combine "rpm-only" deltarpm which does not work with filesystem data, specify the -r option.

makedeltarpm normally produces a V3 format deltarpm, use the -V option to specify a different version if desired. The -z option can be used to specify a different compression method, the default is to use the same compression method as used in the new rpm.

The -s option makes makedeltarpm write out the sequence id to the specified file seqfile.

If you also use patch rpms you should use the -p option to specify the rpm-print of oldrpm and the created patch rpm. This option tells makedeltarpm to exclude the files that were not included in the patch rpm but are not byteswise identical to the ones in oldrpm.

makedeltarpm can also create an "identity" deltarpm by adding the -u switch. In this case only one rpm has to be specified. An identity deltarpm can be useful to just replace the signature header of a rpm or to reconstruct a rpm from the filesystem.

## MEMORY CONSIDERATIONS
makedeltarpm normally needs about three to four times the size of the rpm's uncompressed payload. You can use the -m option to enable a sliding block algorithm that needs mbytes megabytes of memory. This trades memory usage with the size of the created deltarpm. Furthermore, the uncompressed deltarpm payload is currently also stored in memory when this option is used, but it tends to be small in most cases.

## SEE ALSO
applydeltarpm(8) combinedeltarpm(8)

## AUTHOR
Michael Schroeder <mls@suse.de>


dhcdrop

package: dhcdrop

title: dhcdrop(8)

text:
# dhcdrop(8)

## NAME
dhcdrop - program for searching and suppress false DHCP servers in Ethernet.

## SYNOPSIS
dhcdrop [ -h ] [ -D ] [ -t ] [ -y ] [ -r ] [ -b ] [ -a ] [ -A ] [ -f ] [ -R ] [ -q ]

[ -m count ] [ -c count ] [ -n hostname ] [ -N clientname ] [ -p port ] [ -P port ] [ -w seconds ]

[ -T timeout ] [ -M max-hosts-scan ] [ -l MAC-address ] [ -L network ] [ -S network/mask ] [ -F from-IP ]

[ -s server-IP ] [ -C children count (2 - 32) ]

[ initial-MAC-address ] < -i interface-name|interface-index >

## DESCRIPTION
Suppressing DHCP server is made by dhcdrop with a help of an attack DHCP starvation or with a help of flooding with DHCPDISCOVER messages. Look for details below. Besides dhcdrop can be used as a diagnostical tool and stress-testing when setting and developing DHCP servers

## OPTIONS
-h

prints help-message and also codes of program's return.

-D

list of available network interfaces. Format - index:name.

-t

test mode. Using this mode dhcdrop does not execute suppression of server. DHCPDISCOVER is being sent. If the answer comes to it from the non-ignored server then the program is completes returning code 200 and printing the string:

DHCP SRV: 10.7.7.1 (IP-hdr: 10.7.7.1) SRV ether: 00:02:44:75:77:E4, YIP: 10.7.7.205

which consists of the MAC address of found false DHCP server.

-y

answer 'yes' to all questions.

-r

disable ethernet address randomize. Every further source MAC address differs from previous for 1.

-b

points on necessity of using flag BROADCAST in DHCP packets sent.

-a

always wait for server's response to default DHCP client port (68) even if a number of client's port set differs from default value.

-A

always wait for server's response from default DHCP server port (67), even if a number of client's port set differs from default value.

-f

flood mode with DHCPDISCOVER requests. SHOULD BE USED ATTENTIVELY. It is convenient for stress-testing of the server. In case of using option -r all the packets sent have the same MAC address.

-R

send DHCPRELEASE from source MAC address specified by <initial MAC address> and IP address specified by option -F to server specified by option -s

-q

quiet mode.

-m count

maximum number of attempts to receive answer from DHCP server. (default: 5).

-c count

maximum number of receiving addresses from DHCP server (default: 255).

-n hostname

value of DHCP-option 'HostName' (default: 'DHCP-dropper').

-N clientname

value of DHCP-option 'Vendor-Class' (default: 'DHCP-dropper').

-p port

set client port value (default: 68).

-P port

set server port value (default: 67).

-w seconds

set timeout after which the process will be restarted when using agressive mode (see option -L ) (default: 60 secs).

-T timeout

set timeout of waiting server response in seconds (default: 3).

-M maximum-hosts

maximum number of hosts scanned if agressive mode used (option -L).

-l MAC-address

ethernet address of DHCP server which need to ignore. May be several servers. Need option -l for each server.

-L legal-network

specify legal network(s) on interfase. May be several networks. If this parameter is set, dhcdrop uses agressive mode: it scans address range assigned by DHCP server for searching hosts with incorrect addresses, sends DHCPRELEASE to server from every found host after this it restarts process of receiving addreses. Need option -L for each network.

-S network/mask

ARP-scan for network 'network' with network mask 'mask' (CIDR notation). Source IP address for scanning specified by option -F If source IP is not set - using random IP address from network address range.

-F source-ip

source IP for scanning network or sending DHCPRELEASE (see option -S and -R ).

-s server-ip-adress

specify DHCP server IP address. Used with option -R

-C count

children number (default: 0, minimal value: 2, maximum: 32). Compatible only with flag -f

initial-MAC-address

specify source MAC address for sending first DHCP message. If address not set - used random value.

-i interface

defines network interface, can be name or index (cannot be 'any'). For listing available interfaces use option -D

## THEORETICAL BASICS
In DHCP protocol there is an option which specifies duration of leasing an IP address (Lease Time). During this time DHCP server gives IP address for client's use. After this time period a client have to make an attempt to refresh IP address for the purpose of extension the lease. For the server giving out IP address in lease means that during the lease this IP address can be given only to an owner of the lease and nobody else. Identification of clients is usually done by the server on the ground of MAC address. Usually every server has a pool of dynamic IP addresses. These are addresses which are not assigned to concrete MAC addresses and are given dynamically after any client's request. Pool on SOHO routers with default settings is not very big - from tens to about 200 addresses. In case of using software which performs the function of DHCP server the size of the pool is defined by the one who sets. If the pool of addresses is over then DHCP server ignores the requests from new clients (probably documenting this in logs). Actually it's not in action.

Thereby in case of appearance false DHCP they can be supressed rather easy. It's necessary to receive lease for every IP address available on this server sending requests from unique clients every time. The more Lease Time is in server settings, the bigger period of DHCP server suppression in case of exhaustion of dynamical pool is. For most of SOHO routers Lease time comes to a number of days or even weeks. In case of using WinGate, dhcpd and other similar soft as DHCP server the lease time depends on the fantasy of the man who launched false DHCP server.

## PRINCIPLE OF DHCDROP OPERATION
The program opens the interface specified in command line options using promiscuous mode then forms DHCP message (DHCPDISCOVER) using random source MAC address (if another conduct isn't specified) and sends it to the interface:

```
01:58:04.681600 00:70:de:3b:b9:05 > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800),
length 342: (tos 0x10, ttl 64, id 33964, offset 0, flags [none],
proto UDP (17), length 328)
0.0.0.0.68 > 255.255.255.255.67: BOOTP/DHCP, Request from 00:70:de:3b:b9:05,
length 300, xid 0xcc1cfc5c, Flags [none]

          Client-Ethernet-Address 00:70:de:3b:b9:05

          Vendor-rfc1048 Extensions

            Magic Cookie 0x63825363

            DHCP-Message Option 53, length 1: Discover

            Parameter-Request Option 55, length 3:

              Domain-Name-Server, Default-Gateway, Subnet-Mask

            Hostname Option 12, length 12: "DHCP-dropper"

            Vendor-Class Option 60, length 12: "DHCP-dropper"

            Client-ID Option 61, length 7: ether 00:70:de:3b:b9:05
```

After this it starts to wait for server's answer (DHCPOFFER). If the answer with offering IP address lease is received then the next DHCP message (DHCPREQUEST) is send to the interface. On this message server answers with DHCPACK-packet which confirms the possibility of using the IP address by a client. This completes the operation of receiving IP address suggested by the server. The program changes source MAC address and sends DHCPDISCOVER again. After that all the above operations of receiving the lease of a new IP address are repeated. It's worth paying attention that the program changes not only the client's MAC address in DHCP message but also the MAC address in the header of Ethernet-frame. This possibility brings the work of the program maximally nearer to the work of real DHCP client (and also allows to avoid DHCP snooping).

Cycle of receiving IP addresses from server comes to an end when the maximum number of IP addresses set by the option is received or in case of exhausting dynamical pool of the server. In the second case you gained a victory. In the first case if you have an aim to reject the DHCP server then there is a point to set another value of maximum number of leased address option.

## USAGE OF THE PROGRAM
Interfaces listing

First of all it's necessary to understand how the network interface, where there is DHCP server, is called. This is easy to understand in UNIX-like OS by outputting ifconfig command. But in Windows OS it is not so evident. Because of this let's launch the program with -D option first of all:

```
C:>dhcdrop -D
Available interfaces:
1:\Device\NPF_GenericDialupAdapter

  descr: Adapter for generic dialup and VPN capture
2:\Device\NPF_{0C796DB5-22D9-46AB-9301-9C7ADC2304AF}

  descr: ZyXEL GN650 1000Base-T Adapter          (Microsoft's Packet Scheduler)

  iaddr: 192.168.1.2/24  bcast: 255.255.255.255

  iaddr: 10.7.7.7/24  bcast: 255.255.255.255
```

According to the output information it's evident that we need the second interface. As an argument for program's option -i any index of the second interface or its name \Device\NPF_{0C796DB5-22D9-46AB-9301-9C7ADC2304AF} can be set. To my mind it's more easy to use index and to launch the program with pointing index instead of a name. For example: dhcdrop -i 2

Interactive mode, by default

The easiest way of using the program for searching and choosing the rejected server manually:

```
$ sudo dhcdrop -i eth1
Using interface: 'eth1'
Got response from server 10.7.7.1 (IP-header 10.7.7.1), server ethernet address: 00:02:44:75:77:E4, lease time: 1.1h (3960s)
Got BOOTREPLY (DHCPOFFER) for client ether: 00:16:09:D8:CF:60 You IP: 10.7.7.201/24
Drop him? [y/n] n
Searching next server...
Got response from server 192.168.1.1 (IP-header 192.168.1.1), server ethernet address: 00:1E:2A:52:C8:CA, lease time: 24h (86400s)
Got BOOTREPLY (DHCPOFFER) for client ether: 00:16:09:D8:CF:60 You IP: 192.168.1.2/24
Drop him? [y/n] y
1. Got BOOTREPLY (DHCPACK) for client ether: 00:16:09:D8:CF:60 You IP: 192.168.1.2/24
2. Got BOOTREPLY (DHCPACK) for client ether: 00:A2:FA:12:41:F7 You IP: 192.168.1.3/24
3. Got BOOTREPLY (DHCPACK) for client ether: 00:56:EA:F8:1C:B0 You IP: 192.168.1.4/24
4. Got BOOTREPLY (DHCPACK) for client ether: 00:EA:91:1A:C8:A8 You IP: 192.168.1.5/24
5. Got BOOTREPLY (DHCPACK) for client ether: 00:83:8A:25:C7:1C You IP: 192.168.1.6/24
6. Got BOOTREPLY (DHCPACK) for client ether: 00:CA:A7:FF:C1:70 You IP: 192.168.1.7/24
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Finished.
```

As it's seen from the example when receiving an answer from DHCP server dhcdrop reports information from the server about given IP address and asks of necessity to suppress this server. Receiving a negative answer it goes on searching for servers in the network ignoring the server discovered before. In case of receiving a positive answer it starts a process for rejecting the server with a method shown above.

Automatical suppresion mode of all the servers except the legitimate one

In case of knowing (and usually we know) MAC address of the legal DHCP server in our network the operation of suppressing illegal servers can be simplified:

```
$ sudo dhcdrop -i eth1 -y -l 00:02:44:75:77:E4
Using interface: 'eth1'
Got response from server 192.168.1.1 (IP-header 192.168.1.1), server ethernet address: 00:1E:2A:52:C8:CA, lease time: 24h (86400s)
Got BOOTREPLY (DHCPOFFER) for client ether: 00:37:C5:10:BE:16 You IP: 192.168.1.2/24
1. Got BOOTREPLY (DHCPACK) for client ether: 00:37:C5:10:BE:16 You IP: 192.168.1.2/24
2. Got BOOTREPLY (DHCPACK) for client ether: 00:94:26:88:33:BD You IP: 192.168.1.3/24
3. Got BOOTREPLY (DHCPACK) for client ether: 00:E5:AC:7B:79:BB You IP: 192.168.1.4/24
<skipped>
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Finished.
```

In this version of using dhcdrop rejects any server except that ones states with -l option without asking additional questions (due to using option -y ).

Test mode

Test mode ( -t ) is comfortable to use for execution the program from code in computer-aided mode. An example of the simplest code is below:

```
00 #!/bin/bash
01 LEGAL_SERVER="00:11:22:33:44:55"
02 DROPPER="/usr/sbin/dhcdrop"
03 IFNAME="eth1"
04 $DROPPER -i $IFNAME -t -l $LEGAL_SERVER -m 3
05 if [ $? = 200 ]
06 then
07    echo Illegal server found Dropping him
08    $DROPPER -i eth1 -l $LEGAL_SERVER -y
09 else
10    echo Illegal server not found.
11 fi
```

In the forth line launching of dhcdrop is being executed in a test mode with setting an option of legal DHCP server for the network ( -l ), an option of testing ( -t ) and an option of setting maximum number of attempts of sending DHCPDISCOVER in mode of searching the server ( -m). If there is no answer for all the requests been sent then the program ends with 0 code. If there is answer for the server without -l option then the program ends with 200 code which leads to the further launching of the program with options describing suppression of any DHCP server in the network except the legal one.

Usage of aggressive mode for receiving addresses

As you can guess from the description of DHCP protocol - if a client received the configuration from illegal DHCP server then the server wouldn't give this configuration iteratively to another client until the period of lease expires. So a simple exhaustion of IP addresses' pool won't save clients who have already received incorrect configuration. The server will give these addresses only to the clients who requested them initially and will ignore requests from dhcdrop information from illegal DHCP server again and it would be continued until illegal DHCP server switched off. For solving such a problem there were added the aggressive mode of receiving IP addresses in dhcdrop starting with version 0.5. It is activated with -L option which points a legitimate IP subnet for the given Etherner segment of the network. Here is the algorithm of its operation: dhcdrop launches an ordinary mode of suppression and exhausts the whole IP addresses' pool of illegal DHCP server. Analyzes the first DHCPOFFER received from illegal DHCP, with a help of the network mask and client's IP address given out by the server receives the address of IP network attended by this server. Launches ARP-scanning of received subnet for the purpose of exposing hosts which received incorrect configurational information, default number of scanned hosts is limited to 512 (can be changed with -M option), some servers gives out configurational set with a mask /8 which conforms to approximately 16 million of hosts - scanning of such an address range will take a lot of time. Sends messages DHCPRELEASE to the DHCP server from every found host (except the server itself). Waits 60 seconds (default value can be changed with -w option), after then restarts the process of receiving IP addresses. As an example let's launch dhcdrop with the same options as in the previous example but additionally state legal IP network 10.7.7.0:

```
$ sudo dhcdrop -i eth1 -y -l 00:02:44:75:77:E4 -L 10.7.7.0
Using interface: 'eth1'
Got response from server 192.168.1.1 (IP-header 192.168.1.1), server ethernet address: 00:1E:2A:52:C8:CA, lease time: 24h (86400s)
Got BOOTREPLY (DHCPOFFER) for client ether: 00:BC:BF:D6:39:2E You IP: 192.168.1.5/24
1. Got BOOTREPLY (DHCPACK) for client ether: 00:BC:BF:D6:39:2E You IP: 192.168.1.5/24
2. Got BOOTREPLY (DHCPACK) for client ether: 00:FB:E7:A4:19:EC You IP: 192.168.1.6/24
3. Got BOOTREPLY (DHCPACK) for client ether: 00:CB:44:F9:A8:6F You IP: 192.168.1.7/24
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Trying to use agressive mode.
Starting ARP scanning network in range: 192.168.1.0 - 192.168.1.255...
Illegal DHCP server perhaps assigned IP adresses to the following hosts:
1. Received ARP-reply from: 00:1e:2a:52:c8:ca (192.168.1.1) - itself DHCP server.
2. Received ARP-reply from: 00:03:ff:15:52:90 (192.168.1.3)
3. Received ARP-reply from: 00:03:ff:14:52:90 (192.168.1.4)
4. Received ARP-reply from: 00:a0:c5:30:52:90 (192.168.1.200)
Sending DHCPRELEASE for invalid clients:
Send DHCPRELEASE for host 00:03:ff:15:52:90 (192.168.1.3).
Send DHCPRELEASE for host 00:03:ff:14:52:90 (192.168.1.4).
Send DHCPRELEASE for host 00:a0:c5:30:52:90 (192.168.1.200).
Restart dropping DHCP server after 60 seconds timeout...
1. Got BOOTREPLY (DHCPACK) for client ether: 00:BC:BF:D6:39:2E You IP: 192.168.1.5/24
2. Got BOOTREPLY (DHCPACK) for client ether: 00:F1:32:14:60:A3 You IP: 192.168.1.3/24
3. Got BOOTREPLY (DHCPACK) for client ether: 00:2D:1C:80:ED:12 You IP: 192.168.1.4/24
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
Wait DHCPOFFER timeout. Resending DHCPDISCOVER.
WARNING: Failed to take away all the IP addresses assigned by DHCP server.
Perhaps DHCP server checks availability of IP addresses by sending ARP-request
before assigning them. Try to restart dhcpdrop later. If it doesn't help
try to disconnect problem hosts temporarily, then send manually DHCPRELEASE
from address of this hosts (use option -R) and restart dhcdrop.
Finished.
```

Explanation of the program operation's results.

After outputting the inscription "Trying to use aggressive mode" ARP-scanning of subnet, serviced by illegal DHCP server in the stated range, starts. As a result 4 hosts are found including the DHCP server itself (the first host). Then dhcdrop sends DHCPRELEASE message to the server 192.168.1.1 from addresses (Ethernet & IP) of all the hosts found in the subnet except DHCP server itself and stops execution for 60 seconds. Timeout is necessary because some DHCP servers hold giving out IP addresses to a new client during little period of time after receiving DHCPRELEASE from a previous client. In case of necessity timeout's value can be changed with -w option. On the expiry of timeout dhcdrop launches the process of receiving released IP addresses. We succeeded in receiving IP addresses 192.168.1.5 (it was received initially when starting the program), 192.168.1.3 and 192.168.1.4. The last two addresses were successfully released by the server after receiving DHCPRELEASE messages generated by dhcdrop. Failed to receive the address 192.168.1.200, in spite of presence of this host in the network, and the fact that from its address DHCPRELEASE message was send. One of the reasons of failure was described in warning in the end of the program's output: DHCP server before giving out the addresses can check if the host with the requested IP address exists and only after this it can give out the address if such a host is absent in the network. If not, a new lease for this address will not be given out. In this situation switching off the problem hosts fron the network manually and sending DHCPRELEASE messages from these hosts' addresses to the server (see an example below) can be helpful. After this it's necessary to restart the process of receiving IP addresses. But in our case the problem isn't hidden here. The host 192.168.1.200 has a statically set IP address and because of this it has never requested the configuration from DHCP server. The necessity itself of stating the legal network for launching the aggressive mode is necessary to check of the address range given out by illegal DHCP server crosses the address range of the subnet where it was discovered. If the address ranges cross each other then ARP-scanning will be done with the hosts, which have the correct configuration and will output the incorrect information. Because of this in case of discovering crossing of the address ranges aggressive mode will not be launched.

Sending DHCPRELEASE message

You will probably have a necessity to send DHCPRELEASE message manually. For example, because of the reason mentioned in the previous example. You can do it with a help of -R option:

```
$ sudo dhcdrop -i eth1 -R -s 192.168.1.1 -F 192.168.1.4 00:2D:1C:80:ED:12
Using interface: 'eth1'
Send DHCPRELEASE from 00:2D:1C:80:ED:12 client IP 192.168.1.4 to DHCP server 192.168.1.1
Finished.
```

Option -s sets server's IP address, -F set DHCP client's IP address, 00:2D:1C:80:ED:12 set client's Ethernet address. As a result such a sort of packet will be send in the network:

```
16:13:43.887735 00:2d:1c:80:ed:12 > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342:
(tos 0x10, ttl 64, id 29807, offset 0, flags [none], proto UDP (17), length 328)
0.0.0.0.68 > 192.168.1.1.67: BOOTP/DHCP, Request from 00:2d:1c:80:ed:12,
length 300, xid 0xb2f04a28, Flags [none]

    Client-IP 192.168.1.4

    Client-Ethernet-Address 00:2d:1c:80:ed:12

    Vendor-rfc1048 Extensions

    Magic Cookie 0x63825363

    DHCP-Message Option 53, length 1: Release

    Server-ID Option 54, length 4: 192.168.1.1

    Client-ID Option 61, length 7: ether 00:2d:1c:80:ed:12
```

Scanning the network's segment

You can use ARP-scanning of the network for searching clients who received incorrect configurational information. It is realized with a help of -S option:

```
$ dhcdrop -i eth1 -S 192.168.1.0/24
Using interface: 'eth1'
Starting ARP-scanning for subnet 192.168.1.0/24.
IP address range 192.168.1.0 - 192.168.1.255.
WARNING: Source IP is not set (use option -F).
Using random value for source IP address: 192.168.1.195
1. Received ARP-reply from: 00:1e:2a:52:c8:ca (192.168.1.1).
2. Received ARP-reply from: 00:a0:c5:30:52:90 (192.168.1.200).
Finished.
```

According to the warning, which was printed by the program, when launching, the source IP address wasn't set. Because of this dhcdrop chooses a random IP address from address range of a stated subnet. If you need to set a source address then use -F option. For this kind of scanning factual settings of routing in your network aren't important. Interface set by an option -i will always be used accepting that hosts of the mentioned subnet are in the same Ethernet segment with the host where dhcdrop is being launched. Also this option allows to discover duplication of IP addresses in the same segment of the network even if the scanning is being done from the host which IP address is being duplicated by another host.

## AUTHOR
This program was written by Roman Chebotarev <roma@ultranet.ru>

## REPORTING BUGS
Any bugs/remarks/suggestions/wishes concerning this program please send to <roma@ultranet.ru>

## MAN FILE
Guidance page was made by Andrew Clark <andyc@altlinux.org>, basing on the articles of the author of the program, web page http://www.netpatch.ru/en/dhcdrop.html

## TRANSLATION
The translation from Russian into English was made by Anna Makhtinger <mailmnoo@rambler.ru>