apt-get

title: apt-get(8)

text:
# apt-get(8)

## NAME
apt-get - APT package handling utility -- command-line interface

## SYNOPSIS
apt-get [ -hvs ] [ -o=config string ] [ -c=file ] [ update ] [ upgrade ] [ dselect-upgrade ] [ install pkg... ] [ remove pkg... ] [ autoremove ] [ source pkg... ] [ build-dep pkg... ] [ check ] [ clean ] [ autoclean ]

## DESCRIPTION
apt-get is the command-line tool for handling packages, and may be considered the user's "back-end" to other tools using the APT library. Several "front-end" interfaces exist, such as dselect(8), aptitude, synaptic, gnome-apt and wajig.

Unless the -h, or --help option is given, one of the commands below must be present.

update

update is used to resynchronize the package index files from their sources. The indexes of available packages are fetched from the location(s) specified in /etc/apt/sources.list. For example, when using a Debian archive, this command retrieves and scans the Packages.gz files, so that information about new and updated packages is available. An update should always be performed before an upgrade or dist-upgrade. Please be aware that the overall progress meter will be incorrect as the size of the package files cannot be known in advance.

upgrade

upgrade is used to install the newest versions of all packages currently installed on the system from the sources enumerated in /etc/apt/sources.list. Packages currently installed with new versions available are retrieved and upgraded; under no circumstances are currently installed packages removed, or packages not already installed retrieved and installed. New versions of currently installed packages that cannot be upgraded without changing the install status of another package will be left at their current version. An update must be performed first so that apt-get knows that new versions of packages are available.

dselect-upgrade

dselect-upgrade is used in conjunction with the traditional Debian packaging front-end, dselect(8). dselect-upgrade follows the changes made by dselect(8) to the Status field of available packages, and performs the actions necessary to realize that state (for instance, the removal of old and the installation of new packages).

dist-upgrade

dist-upgrade, in addition to performing the function of upgrade, also intelligently handles changing dependencies with new versions of packages; apt-get has a "smart" conflict resolution system, and it will attempt to upgrade the most important packages at the expense of less important ones if necessary. The /etc/apt/sources.list file contains a list of locations from which to retrieve desired package files. See also apt_preferences(5) for a mechanism for overriding the general settings for individual packages.

install

install is followed by one or more packages desired for installation. Each package is a package name, not a fully qualified filename (for instance, in a Debian GNU/Linux system, libc6 would be the argument provided, not libc6_1.9.6-2.deb). All packages required by the package(s) specified for installation will also be retrieved and installed. The /etc/apt/sources.list file is used to locate the desired packages. If a hyphen is appended to the package name (with no intervening space), the identified package will be removed if it is installed. Similarly a plus sign can be used to designate a package to install. These latter features may be used to override decisions made by apt-get's conflict resolution system. A specific version of a package can be selected for installation by following the package name with an equals and the version of the package to select. This will cause that version to be located and selected for install. Alternatively a specific distribution can be selected by following the package name with a slash and the version of the distribution or the Archive name (stable, testing, unstable).

Both of the version selection mechanisms can downgrade packages and must be used with care.

Finally, the apt_preferences(5) mechanism allows you to create an alternative installation policy for individual packages.

If no package matches the given expression and the expression contains one of '.', '?' or '*' then it is assumed to be a POSIX regular expression, and it is applied to all package names in the database. Any matches are then installed (or removed). Note that matching is done by substring so 'lo.*' matches 'how-lo' and 'lowest'. If this is undesired, anchor the regular expression with a '^' or '$' character, or create a more specific regular expression.

remove

remove is identical to install except that packages are removed instead of installed. If a plus sign is appended to the package name (with no intervening space), the identified package will be installed instead of removed.

autoremove

autoremove is used to remove packages that were automatically installed to satisfy dependencies for other packages and are now no longer needed as dependencies changed or the package(s) needing them were removed in the meantime.

source

source causes apt-get to fetch source packages. APT will examine the available packages to decide which source package to fetch. It will then find and download into the current directory the newest available version of that source package. Source packages are tracked separately from binary packages via deb-src type lines in the sources.list(5) file. This probably will mean that you will not get the same source as the package you have installed or as you could install. If the --compile options is specified then the package will be compiled to a binary .deb using dpkg-buildpackage, if --download-only is specified then the source package will not be unpacked. A specific source version can be retrieved by postfixing the source name with an equals and then the version to fetch, similar to the mechanism used for the package files. This enables exact matching of the source package name and version, implicitly enabling the APT::Get::Only-Source option.

Note that source packages are not tracked like binary packages, they exist only in the current directory and are similar to downloading source tar balls.

build-dep

build-dep causes apt-get to install/remove packages in an attempt to satisfy the build dependencies for a source package.

check

check is a diagnostic tool; it updates the package cache and checks for broken dependencies.

clean

clean clears out the local repository of retrieved package files. It removes everything but the lock file from /var/cache/apt/archives/ and /var/cache/apt/archives/partial/. When APT is used as a dselect(8) method, clean is run automatically. Those who do not use dselect will likely want to run apt-get clean from time to time to free up disk space.

autoclean

Like clean, autoclean clears out the local repository of retrieved package files. The difference is that it only removes package files that can no longer be downloaded, and are largely useless. This allows a cache to be maintained over a long period without it growing out of control. The configuration option APT::Clean-Installed will prevent installed packages from being erased if it is set to off.

## OPTIONS
All command line options may be set using the configuration file, the descriptions indicate the configuration option to set. For boolean options you can override the config file by using something like -f-,--no-f, -f=no or several other variations.

-d

--download-only

Download only; package files are only retrieved, not unpacked or installed. Configuration Item: APT::Get::Download-Only.

-f

--fix-broken

Fix; attempt to correct a system with broken dependencies in place. This option, when used with install/remove, can omit any packages to permit APT to deduce a likely solution. Any Package that are specified must completely correct the problem. The option is sometimes necessary when running APT for the first time; APT itself does not allow broken package dependencies to exist on a system. It is possible that a system's dependency structure can be so corrupt as to require manual intervention (which usually means using dselect(8) or dpkg --remove to eliminate some of the offending packages). Use of this option together with -m may produce an error in some situations. Configuration Item: APT::Get::Fix-Broken.

-m

--ignore-missing

--fix-missing

Ignore missing packages; If packages cannot be retrieved or fail the integrity check after retrieval (corrupted package files), hold back those packages and handle the result. Use of this option together with -f may produce an error in some situations. If a package is selected for installation (particularly if it is mentioned on the command line) and it could not be downloaded then it will be silently held back. Configuration Item: APT::Get::Fix-Missing.

--no-download

Disables downloading of packages. This is best used with --ignore-missing to force APT to use only the .debs it has already downloaded. Configuration Item: APT::Get::Download.

-q

--quiet

Quiet; produces output suitable for logging, omitting progress indicators. More q's will produce more quiet up to a maximum of 2. You can also use -q=# to set the quiet level, overriding the configuration file. Note that quiet level 2 implies -y, you should never use -qq without a no-action modifier such as -d, --print-uris or -s as APT may decided to do something you did not expect. Configuration Item: quiet.

-s

--simulate

--just-print

--dry-run

--recon

--no-act

No action; perform a simulation of events that would occur but do not actually change the system. Configuration Item: APT::Get::Simulate. Simulate prints out a series of lines each one representing a dpkg operation, Configure (Conf), Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with and empty set of square brackets meaning breaks that are of no consequence (rare).

-y

--yes

--assume-yes

Automatic yes to prompts; assume "yes" as answer to all prompts and run non-interactively. If an undesirable situation, such as changing a held package or removing an essential package occurs then apt-get will abort. Configuration Item: APT::Get::Assume-Yes.

-u

--show-upgraded

Show upgraded packages; Print out a list of all packages that are to be upgraded. Configuration Item: APT::Get::Show-Upgraded.

-V

--verbose-versions

Show full versions for upgraded and installed packages. Configuration Item: APT::Get::Show-Versions.

--no-list-columns

Display package lists without arranging them in columns. By default, package lists are printed in the style of the "ls" command. Configuration Item: APT::Get::List-Columns.

-b

--compile

--build

Compile source packages after downloading them. Configuration Item: APT::Get::Compile.

--ignore-hold

Ignore package Holds; This causes apt-get to ignore a hold placed on a package. This may be useful in conjunction with dist-upgrade to override a large number of undesired holds. Configuration Item: APT::Ignore-Hold.

--no-upgrade

Do not upgrade packages; When used in conjunction with install no-upgrade will prevent packages listed from being upgraded if they are already installed. Configuration Item: APT::Get::Upgrade.

--force-yes

Force yes; This is a dangerous option that will cause apt to continue without prompting if it is doing something potentially harmful. It should not be used except in very special situations. Using force-yes can potentially destroy your system! Configuration Item: APT::Get::force-yes.

--print-uris

Instead of fetching the files to install their URIs are printed. Each URI will have the path, the destination file name, the size and the expected md5 hash. Note that the file name to write to will not always match the file name on the remote site! This also works with the source and update commands. When used with the update command the MD5 and size are not included, and it is up to the user to decompress any compressed files. Configuration Item: APT::Get::Print-URIs.

--purge

Use purge instead of remove for anything that would be removed. An asterisk ("*") will be displayed next to packages which are scheduled to be purged. Configuration Item: APT::Get::Purge.

--reinstall

Re-Install packages that are already installed and at the newest version. Configuration Item: APT::Get::ReInstall.

--list-cleanup

This option defaults to on, use --no-list-cleanup to turn it off. When on apt-get will automatically manage the contents of /var/lib/apt/lists to ensure that obsolete files are erased. The only reason to turn it off is if you frequently change your source list. Configuration Item: APT::Get::List-Cleanup.

--autoremove

--auto-remove

Remove packages that were automatically installed to satisfy dependencies for other packages and are now no longer needed. Configuration Item: APT::Get::AutomaticRemove.

-t

--target-release

--default-release

This option controls the default input to the policy engine, it creates a default pin at priority 990 using the specified release string. The preferences file may further override this setting. In short, this option lets you have simple control over which distribution packages will be retrieved from. Some common examples might be -t '2.1*' or -t unstable. Configuration Item: APT::Default-Release; see also the apt_preferences(5) manual page.

--trivial-only

Only perform operations that are 'trivial'. Logically this can be considered related to --assume-yes, where --assume-yes will answer yes to any prompt, --trivial-only will answer no. Configuration Item: APT::Get::Trivial-Only.

--no-remove

If any packages are to be removed apt-get immediately aborts without prompting. Configuration Item: APT::Get::Remove

--only-source

Only has meaning for the source command. Indicates that the given source names are not to be mapped through the binary table. This means that if this option is specified, the source command will only accept source package names as arguments, rather than accepting binary package names and looking up the corresponding source package. Configuration Item: APT::Get::Only-Source

--diff-only

--tar-only

Download only the diff or tar file of a source archive. Configuration Item: APT::Get::Diff-Only and APT::Get::Tar-Only

--arch-only

Only process architecture-dependent build-dependencies. Configuration Item: APT::Get::Arch-Only

--enable-upgrade

Enables 'upgrade' action with old behaviour: upgrading only installed packages. 'upgrade' should be used with caution since it can leave system in a broken state. It is advised to use 'dist-upgrade' action instead of 'upgrade' action. Configuration Item: APT::Get::EnableUpgrade.

-h

--help

Show a short usage summary.

-v

--version

Show the program version.

-c

--config-file

Configuration File; Specify a configuration file to use. The program will read the default configuration file and then this configuration file. If configuration settings need to be set before the default configuration files are parsed specify a file with the APT_CONFIG environment variable. See apt.conf(5) for syntax information.

-o

--option

Set a Configuration Option; This will set an arbitrary configuration option. The syntax is -o Foo::Bar=bar.

## FILES
/etc/apt/sources.list

Locations to fetch packages from. Configuration Item: Dir::Etc::SourceList.

/etc/apt/apt.conf

APT configuration file. Configuration Item: Dir::Etc::Main.

/etc/apt/apt.conf.d/

APT configuration file fragments Configuration Item: Dir::Etc::Parts.

/etc/apt/preferences

Version preferences file. This is where you would specify "pinning", i.e. a preference to get certain packages from a separate source or from a different version of a distribution. Configuration Item: Dir::Etc::Preferences.

/var/cache/apt/archives/

Storage area for retrieved package files. Configuration Item: Dir::Cache::Archives.

/var/cache/apt/archives/partial/

Storage area for package files in transit. Configuration Item: Dir::Cache::Archives (implicit partial).

/var/lib/apt/lists/

Storage area for state information for each package resource specified in sources.list(5) Configuration Item: Dir::State::Lists.

/var/lib/apt/lists/partial/

Storage area for state information in transit. Configuration Item: Dir::State::Lists (implicit partial).

## SEE ALSO
apt-cache(8), apt-cdrom(8), , dselect(8), sources.list(5), apt.conf(5), apt-config(8), The APT User's guide in /usr/share/doc/apt/, apt_preferences(5), the APT Howto.

## DIAGNOSTICS
apt-get returns zero on normal operation, decimal 100 on error.

## BUGS
Reporting bugs in APT-RPM is best done in the APT-RPM mailinglist <URL:http://apt-rpm.org/mailinglist.shtml>.

## AUTHOR
Maintainer and contributor information can be found in the credits page <URL:http://apt-rpm.org/about.shtml> of APT-RPM.


acngfs

package: apt-cacher-ng

title: acngfs(8)

text:
# acngfs(8)

## NAME
acngfs - Virtual file system for use with apt-cacher-ng

## SYNOPSIS

```
acngfs BaseURL MountPoint [ proxy=ProxyHost:ProxyPort ] [ cachedir=CachePath ] [ more_acng=settings] [FUSE Mount Options]
```

## DESCRIPTION
acngfs is a FUSE based filesystem which represents files downloadable via HTTP as part of a local filesystem. It has been developed for very specific purposes and is not intended to be a general purpose HTTP filesystem.

The main use case for acngfs is a situation where:

•

The files must not be stored on extra space on the user's system (e.g. because of insufficient disk space to make a temporary copy of downloaded files)

•

Local programs (e.g. apt, dpkg) need to read the packages from a local filesystem

•

When reading, certain files might need to be fetched in background (or updated) and this process needs to be triggered somehow

•

Network latency and speed are not relevant, e.g. accessing apt-cacher-ng via localhost connection

•

The proxy service can work efficiently with many requests for small data ranges (apt-cacher-ng, for example)

•

Pattern matching on paths is sufficient to distinguish file and directory names

If the apt-cacher-ng instance happens to run on the same system as acngfs or its cache repository is mounted via fast remote file system, this cache repository can be optionally specified as alternative source path. In this cache, acngfs will attempt to read files directly from this filesystem where possible, reducing network latency and avoiding additional load of apt-cacher-ng server. The directory levels of BaseURL and CachePath should match.

## EXAMPLES
Typical use may be to let apt/dpkg use package file like they are present on the local filesystem so there is no need to download them. In sources.list, the source appears as a file:/ type URL, like:

deb file:/var/local/acngfs_debian unstable main contrib

and the filesystem backend is prepared with a command like:

/usr/lib/apt-cacher-ng/acngfs http://ftp.uni-kl.de/debian proxy=cacheBox:3142 /var/local/acngfs_debian -o allow_root

or for a locally installed apt-cacher-ng with common Debian cache repository stored in /var/cache/apt-cacher-ng/debrep:

/usr/lib/apt-cacher-ng/acngfs http://ftp.uni-kl.de/debian /var/cache/apt-cacher-ng/debrep proxy=localhost:3142 cachedir=/var/local/acngfs_debian -o allow_root

## OPTIONS
The command-line options supported by acngfs are:

BaseURL

Remote mirror to be used as real source, like http://ftp2.de.debian.org/debian. NOTE: the mirror subdirectory part (like debian) should be added either to BaseURL or to the path in sources.list, not to both.

ProxyURL

Complete or simplified host and port specification of the proxy server, http://localhost:3142.

CachePath

Optional hint, a directory path pointing to the internal cache subdirectory of apt-cacher-ng where it stores data downloaded from BaseURL. For more details see apt-cacher-ng manual, chapter "Advanced configuration".

mountpoint

Directory representing the URL in the local filesytem.

--help

Print a help summary and additional FUSE application options

FuseOptions

Various options for the FUSE subsystem to control filesystem behaviour. See --help output and FUSE documentation for more details.

## FILES
/usr/lib/apt-cacher-ng/acngfs

Executable binary documented in this manual page

## NOTES
Permissions of the files are important when using mounting when sharing data with other users (including root!). To mount as user and let root use the package management tools (apt, dpkg), one may need to use FUSE options like in the following example:

acngfs http://ftp.uni-kl.de/debian http://localhost:3142 /mnt/misc -o allow_root

See FUSE documentation for details about file permissions representation.

## BUGS
Software is still experimental, use at your own risk!

There are natural limitations on capabilities of the FS: no directory browsing is allowed (only blind descending), permissions of files are inherited from the mount point as well as other properties of the filesystem.

Should be used with apt-cacher-ng version 0.2pre2 or newer; otherwise it could flood log files with many requests from small file chunks.

## SEE ALSO
apt-cacher-ng(8), fusermount(1)

For more information on Apt-Cacher NG, read the User Manual which can be found either in the doc/pdf directory of the software source package or installed in the documentation directory of apt-cacher-ng by your distribution.

branch: sisyphus


apt-cacher-ng

title: apt-cacher-ng(8)

text:
# apt-cacher-ng(8)

## NAME
apt-cacher-ng - caching proxy for software package downloads

## SYNOPSIS

```
apt-cacher-ng [-c confdir] [-h] [optname=optvalue ...]
```

## DESCRIPTION
Apt-Cacher NG is a caching proxy for software packages which are downloaded by Unix/Linux system distribution mechanisms from mirror servers accessible via HTTP.

## OPTIONS
The command-line options supported by apt-cacher-ng are:

-c confdir

Scan the specified configuration directory and interpret configuration files found there.

-h

Short option summary

-i

Ignore some non-critical configuration errors on startup. Regular operation with this switch is not recommended.

-v

Enable additional verbosity in log output.

-e

Invoke expiration task immediately after startup. This option exists for legacy compatibility and can be dangerous to use due to filesystem permission issues (i.e. danger to cause them). Using acngtool to control such operations instead is advisable.

varname=varopt

The options from the configuration can be passed on the command line as key=value pairs.

## CONFIGURATION
Apt-Cacher NG is configured by a multi-config directory, i.e. the configuration is split into many configuration files having names with suffix .conf and stored in a single directory. Variables can override previously configured settings from other files, sometimes those settings are merged (depending on the variable).

The configuration directory is typically /etc/apt-cacher-ng but it can be adjusted with the -c option (see systemd service file for details or wherever the init system starts the daemon).

On Debian systems, there are at least three files installed by default: acng.conf (containing documented examples), security.conf (containing sensible data and only readable for special users) and zz_debconf.conf (containing popular settings which are set by the Debian Configuration mechanism).

## SIGNALS
Only few signals are handled in non-default ways.

SIGUSR1 closes and reopens log files.

SIGTERM and SIGINT close log files and stop the daemon.

## MORE INFORMATION
For more information on Apt-Cacher NG, read the User Manual which can be found either in the doc/pdf directory of the software source package or installed in the documentation directory of apt-cacher-ng by your distribution.


apt-repo

package: apt-repo

title: apt-repo(8)

summary: Manipulate APT repository list

text:
# apt-repo(8)

## NAME
apt-repo — Manipulate APT repository list

## SYNOPSIS
apt-repo

[list] [-a]

apt-repo

list [task] id

apt-repo

add source

apt-repo

rm source|all [type]

apt-repo

set branch

apt-repo

clean

apt-repo

update

apt-repo

test [task] id

apt-repo

upgrade [id]

apt-repo

[-h] [-v]

## DESCRIPTION
The apt-repo script allows to show, add, and remove APT repositories specified by a source in sources.list(5) format, an URL with optional component, a branch name, or a task number.

Since apt-repo relies internally on apt-config(8) to find the files which contain the repository lists, it can be asked to manipulate arbitrary non-system APT sources.list by setting APT_CONFIG, which is a standard environment variable looked into by APT to find its configuration. Example:

APT_CONFIG=~/.hasher/apt-extra.conf apt-repo add p7

will manipulate the repository lists in the files defined (if any) in ~/.hasher/apt-extra.conf. This can be useful, for example, to manipulate a user's local hasher(7) configuration. (Such configurations are described in more detail at https://www.altlinux.org/Hasher/Tips.)

If --dry-run is defined in command line changes only shown, is not performed.

## OPTIONS
list

Show active repositories in sources.list(5) format. If -a is specified, all available repositories are displayed (inactive ones are commented by ‘#’).

list [task] id

Show names of all available packages (except *-devel*, *-checkinstall and *-debuginfo) in a task repository specified by id.

add source

Add source to the list of active repositories.

rm source [<type>]

Remove or comment source if it is active. Special keyword all removes all active sources. The all keyword followed by optional <type> removes all sources of specified type: ‘branch’ or ‘branches’ removes all branch sources, ‘task’ or ‘tasks’ removes all tasks sources, ‘cdrom’ or ‘cdroms’ removes all cdrom sources.

set branch

Removes all exising sources and adds branch branch

clean

Removes all cdrom and task sources.

update

Run apt-get update

to update the APT cache from the active repositories.

test [task] id

Install all available packages (except *-devel*, *-checkinstall and *-debuginfo) from the task repository specified by id.

test [task] id pkg1 pkg2

Install the given packages from the task repository specified by id.

test [task] '' pkg1 pkg2

Install the given packages (without modifying APT repos).

upgrade [id [id]]

Upgrade all packages (including specified task(s) by id ).

-h --help

Print usage information and quit.

-v --version

Print version and quit.

## SOURCE FORMAT

### APT Source
Source can be specified in sources.list(5) format:

apt-repo add "rpm http://git.altlinux.org/repo/39115/ i586 task"

Recognized repository types: rpm, rpm-dir and rpm-src. It is allowed to specify source as separate words. If trailing architecture and component are missing, two lines will be added (current system architecture and ‘noarch’) with component ‘classic’.

### URL
APT supports file://, copy://, http://, ftp://, rsync:// and cdrom:// protocols. URL with required protocol may be followed by an optional architecture and one or more components. If architecture and component are missing, two lines will be added (current system architecture and ‘noarch’) with component ‘classic’. This form is useful to add a branch on a mirror server.

Example:

apt-repo add ftp://mirror.yandex.ru/altlinux/p7/branch

### Absolute Path
Local directory beginning with ‘/’ added as a hasher(7) repository: with current system architecture and ‘hasher’ component.

apt-repo add /opt/repo

### Branch
Branch is a named repository consisting of two parts (current system architecture and 'noarch'). By default, the official server is used. Full form:

apt-repo add branch <name of branch> [<archive_date>]

Keyword ‘branch’ may be omitted. Example:

apt-repo add p7

Running

apt-repo add branch

without the name of a branch displays all available branch names. ‘archive_date’ allows to add archive of branch. Date of archive should be in form YYYYMMDD or YYYY/MM/DD.

### Task
Task is a small repository for one or more subtasks built in http://git.altlinux.org infrastructure. This source is used to install software for test purposes. Any task has a unique number. Full form:

apt-repo add task <number of task>

Keyword ‘task’ may be omitted. Example:

apt-repo add 39115

## FILES
/etc/apt/sources.list

The main list of repositories which APT reads. New repositiories are added here (and, in this case, if it doesn't exist, then it is created).

/etc/apt/sources.list.d/*.list

The additional lists which APT reads.

/etc/apt/apt.conf

/etc/apt/apt.conf.d/*.conf

The system APT configuration which may override the above default paths for sources.list(.d).

## ENVIRONMENT VARIABLES
APT_CONFIG

This value overrides the default place where APT looks for apt.conf. Setting it allows one to manipulate arbitrary user's non-system sources.list by preparing a custom apt.conf (e.g., for hasher).

## SEE ALSO
sources.list(5), apt-cache(8), apt-get(8)

## AUTHORS
Andrey Cherepanov cas@altlinux.org


aptitude

package: aptitude

title: aptitude(8)

summary: high\-level interface to the package manager

text:
# aptitude(8)

## NAME
aptitude - high-level interface to the package manager

## SYNOPSIS
aptitude [<options>...] {autoclean | clean | forget-new | keep-all | update | safe-upgrade}

aptitude [<options>...] {changelog | full-upgrade | download | forbid-version | hold | install | keep-all | markauto | purge | reinstall | remove | show | unhold | unmarkauto} <packages>...

aptitude [<options>...] search <patterns>...

aptitude [-S <fname>] [-i]

aptitude help

## DESCRIPTION
aptitude is a text-based interface to the Debian GNU/Linux package system.

It allows the user to view the list of packages and to perform package management tasks such as installing, upgrading, and removing packages. Actions may be performed from a visual interface or from the command-line.

## COMMAND-LINE ACTIONS
The first argument which does not begin with a hyphen (“-”) is considered to be an action that the program should perform. If an action is not specified on the command-line, aptitude will start up in visual mode.

The following actions are available:

install

Install one or more packages. The packages should be listed after the “install” command; if a package name contains a tilde character (“~”), it will be treated as a search pattern and every package matching the pattern will be installed (see the section “Search Patterns” in the aptitude reference manual). To select a particular version of the package, append “=version” to the package name: for instance, “aptitude install apt=0.3.1”. Similarly, to select a package from a particular archive, append “/archive” to the package name: for instance, “aptitude install apt/experimental”.

Not every package listed on the command line has to be installed; you can tell aptitude to do something different with a package by appending an “override specifier” to the name of the package. For example, aptitude remove wesnoth+ will install wesnoth, not remove it. The following override specifiers are available:

<package>+

Install <package>.

<package>+M

Install <package> and immediately mark it as automatically installed (note that if nothing depends on <package>, this will cause it to be immediately removed).

<package>-

Remove <package>.

<package>_

Purge <package>: remove it and all its associated configuration and data files.

<package>=

Place <package> on hold: cancel any active installation, upgrade, or removal, and prevent this package from being automatically upgraded in the future.

<package>:

Keep <package> at its current version: cancel any installation, removal, or upgrade. Unlike “hold” (above) this does not prevent automatic upgrades in the future.

<package>&M

Mark <package> as having been automatically installed.

<package>&m

Mark <package> as having been manually installed.

As a special case, “install” with no arguments will act on any stored/pending actions.

Note

Once you enter Y at the final confirmation prompt, the “install” command will modify aptitude's stored information about what actions to perform. Therefore, if you issue (e.g.) the command “aptitude install foo bar” and then abort the installation once aptitude has started downloading and installing packages, you will need to run “aptitude remove foo bar” to cancel that order.

remove, purge, hold, unhold, keep, reinstall

These commands are the same as “install”, but apply the named action to all packages given on the command line for which it is not overridden. The difference between hold and keep is that hold will cause a package to be ignored by future safe-upgrade or full-upgrade commands, while keep merely cancels any scheduled actions on the package. unhold will allow a package to be upgraded by future safe-upgrade or full-upgrade commands, without otherwise altering its state. For instance, “aptitude remove '~ndeity'” will remove all packages whose name contains “deity”.

markauto, unmarkauto

Mark packages as automatically installed or manually installed, respectively. Packages are specified in exactly the same way as for the “install” command. For instance, “aptitude markauto '~slibs'” will mark all packages in the “libs” section as having been automatically installed. For more information on automatically installed packages, see the section “Managing Automatically Installed Packages” in the aptitude reference manual.

forbid-version

Forbid a package from being upgraded to a particular version. This will prevent aptitude from automatically upgrading to this version, but will allow automatic upgrades to future versions. By default, aptitude will select the version to which the package would normally be upgraded; you may override this selection by appending “=version” to the package name: for instance, “aptitude forbid-version vim=1.2.3.broken-4”. This command is useful for avoiding broken versions of packages without having to set and clear manual holds. If you decide you really want the forbidden version after all, the “install” command will remove the ban.

update

Updates the list of available packages from the apt sources (this is equivalent to “apt-get update”)

safe-upgrade

Upgrades installed packages to their most recent version. Installed packages will not be removed unless they are unused (see the section “Managing Automatically Installed Packages” in the aptitude reference manual); packages which are not currently installed will not be installed. It is sometimes necessary to remove or install one package in order to upgrade another; this command is not able to upgrade packages in such situations. Use the full-upgrade command to upgrade as many packages as possible.

full-upgrade

Upgrades installed packages to their most recent version, removing or installing packages as necessary. This command is less conservative than safe-upgrade and thus more likely to perform unwanted actions. However, it is capable of upgrading packages that safe-upgrade cannot upgrade.

Note

This command was originally named dist-upgrade for historical reasons, and aptitude still recognizes dist-upgrade as a synonym for full-upgrade.

keep-all

Cancels all scheduled actions on all packages; any packages whose sticky state indicates an installation, removal, or upgrade will have this sticky state cleared.

forget-new

Forgets all internal information about what packages are “new” (equivalent to pressing “f” when in visual mode).

search

Searches for packages matching one of the patterns supplied on the command line. All packages which match any of the given patterns will be displayed; for instance, “aptitude search '~N' edit” will list all “new” packages and all packages whose name contains “edit”. For more information on search patterns, see the section “Search Patterns” in the aptitude reference manual. Unless you pass the -F option, the output of aptitude search will look something like this:

```
i   apt                             - Advanced front-end for dpkg
pi  apt-build                       - frontend to apt to build, optimize and in
cp  apt-file                        - APT package searching utility -- command-
ihA raptor-utils                    - Raptor RDF Parser utilities
```

Each search result is listed on a separate line. The first character of each line indicates the current state of the package: the most common states are p, meaning that no trace of the package exists on the system, c, meaning that the package was deleted but its configuration files remain on the system, i, meaning that the package is installed, and v, meaning that the package is virtual. The second character indicates the stored action (if any; otherwise a blank space is displayed) to be performed on the package, with the most common actions being i, meaning that the package will be installed, d, meaning that the package will be deleted, and p, meaning that the package and its configuration files will be removed. If the third character is A, the package was automatically installed.

For a complete list of the possible state and action flags, see the section “Accessing Package Information” in the aptitude reference guide.

show

Displays detailed information about one or more packages, listed following the search command. If a package name contains a tilde character (“~”), it will be treated as a search pattern and all matching packages will be displayed (see the section “Search Patterns” in the aptitude reference manual). If the verbosity level is 1 or greater (i.e., at least one -v is present on the command-line), information about all versions of the package is displayed. Otherwise, information about the “candidate version” (the version that “aptitude install” would download) is displayed.

You can display information about a different version of the package by appending =version to the package name; you can display the version from a particular archive by appending /archive to the package name. If either of these is present, then only the version you request will be displayed, regardless of the verbosity level.

If the verbosity level is 1 or greater, the package's architecture, compressed size, filename, and md5sum fields will be displayed. If the verbosity level is 2 or greater, the select version or versions will be displayed once for each archive in which they are found.

clean

Removes all previously downloaded files from the package cache directory (usually /var/cache/apt/archives).

autoclean

Removes any cached packages which can no longer be downloaded. This allows you to prevent a cache from growing out of control over time without completely emptying it.

changelog

Downloads and displays the Debian changelog for each of the given source or binary packages. By default, the changelog for the version which would be installed with “aptitude install” is downloaded. You can select a particular version of a package by appending =version to the package name; you can select the version from a particular archive by appending /archive to the package name.

download

Downloads the file for the given package to the current directory. By default, the version which would be installed with “aptitude install” is downloaded. You can select a particular version of a package by appending =version to the package name; you can select the version from a particular archive by appending /archive to the package name.

help

Displays a brief summary of the available commands and options.

## OPTIONS
The following options may be used to modify the behavior of the actions described above. Note that while all options will be accepted for all commands, some options don't apply to particular commands and will be ignored by those commands.

-D, --show-deps

For commands that will install or remove packages (install, full-upgrade, etc), show brief explanations of automatic installations and removals. This corresponds to the configuration option Aptitude::CmdLine::Show-Deps.

-d, --download-only

Download packages to the package cache as necessary, but do not install or remove anything. By default, the package cache is stored in /var/cache/apt/archives. This corresponds to the configuration option Aptitude::CmdLine::Download-Only.

-F <format>, --display-format <format>

Specify the format which should be used to display output from the search command. For instance, passing “%p %V %v” for <format> will display a package's name, followed by its currently installed version and its available version (see the section “Customizing how packages are displayed” in the aptitude reference manual for more information). This corresponds to the configuration option Aptitude::CmdLine::Package-Display-Format.

-f

Try hard to fix the dependencies of broken packages, even if it means ignoring the actions requested on the command line. This corresponds to the configuration item Aptitude::CmdLine::Fix-Broken.

-h, --help

Display a brief help message. Identical to the help action.

--purge-unused

Purge packages that are no longer required by any installed package. This is equivalent to passing “-o Aptitude::Purge-Unused=true” as a command-line argument.

-P, --prompt

Always display a prompt, even when no actions other than those explicitly requested will be performed. This corresponds to the configuration option Aptitude::CmdLine::Always-Prompt.

-R, --without-recommends

Do not treat recommendations as dependencies when installing new packages (this overrides settings in /etc/apt/apt.conf and ~/.aptitude/config). Packages previously installed due to recommendations will not be removed. This corresponds to the pair of configuration options Aptitude::Recommends-Important and Aptitude::Keep-Recommends.

-r, --with-recommends

Treat recommendations as dependencies when installing new packages (this overrides settings in /etc/apt/apt.conf and ~/.aptitude/config). This corresponds to the configuration option Aptitude::Recommends-Important

-s, --simulate

In command-line mode, print the actions that would normally be performed, but don't actually perform them. This does not require root privileges. In the visual interface, always open the cache in read-only mode regardless of whether you are root. This corresponds to the configuration option Aptitude::Simulate.

--schedule-only

For commands that modify package states, schedule operations to be performed in the future, but don't perform them. You can execute scheduled actions by running aptitude install with no arguments. This is equivalent to making the corresponding selections in visual mode, then exiting the program normally. For instance, aptitude --schedule-only install evolution will schedule the evolution package for later installation.

-t <release>, --target-release <release>

Set the release from which packages should be installed. For instance, “aptitude -t experimental ...” will install packages from the experimental distribution unless you specify otherwise. For the command-line actions “changelog”, “download”, and “show”, this is equivalent to appending /release to each package named on the command-line; for other commands, this will affect the default candidate version of packages according to the rules described in apt_preferences(5). This corresponds to the configuration item APT::Default-Release.

-O <order>, --sort <order>

Specify the order in which output from the search command should be displayed. For instance, passing “installsize” for <order> will list packages in order according to their size when installed (see the section “Customizing how packages are sorted” in the aptitude reference manual for more information).

-o <key>=<value>

Set a configuration file option directly; for instance, use -o Aptitude::Log=/tmp/my-log to log aptitude's actions to /tmp/my-log. For more information on configuration file options, see the section “Configuration file reference” in the aptitude reference manual.

-q=n, --quiet=n

Suppress all incremental progress indicators, thus making the output loggable. This may be supplied multiple times to make the program quieter, but unlike apt-get, aptitude does not enable -y when -q is supplied more than once. The optional =n may be used to directly set the amount of quietness (for instance, to override a setting in /etc/apt/apt.conf); it causes the program to behave as if -q had been passed exactly <n> times.

-V, --show-versions

Show which versions of packages will be installed. This corresponds to the configuration option Aptitude::CmdLine::Show-Versions.

-v, --verbose

Causes some commands (for instance, show) to display extra information. This may be supplied multiple times to get more and more information. This corresponds to the configuration option Aptitude::CmdLine::Verbose.

--version

Display the version of aptitude and some information about how it was compiled.

--visual-preview

When installing or removing packages from the command line, instead of displaying the usual prompt, start up the visual interface and display its preview screen.

-w <width>, --width <width>

Specify the display width which should be used for output from the search command (by default, the terminal width is used). This corresponds to the configuration option Aptitude::CmdLine::Package-Display-Width

-y, --assume-yes

When a yes/no prompt would be presented, assume that the user entered “yes”. In particular, suppresses the prompt that appears when installing, upgrading, or removing packages. Prompts for “dangerous” actions, such as removing essential packages, will still be displayed. This option overrides -P. This corresponds to the configuration option Aptitude::CmdLine::Assume-Yes.

-Z

Show how much disk space will be used or freed by the individual packages being installed, upgraded, or removed. This corresponds to the configuration option Aptitude::CmdLine::Show-Size-Changes.

The following options apply to the visual mode of the program, but are primarily for internal use; you generally won't need to use them yourself.

-S <fname>

Loads the extended state information from <fname> instead of the standard state file.

-i

Displays a download preview when the program starts (equivalent to starting the program and immediately pressing “g”).

## ENVIRONMENT
HOME

If $HOME/.aptitude exists, aptitude will store its configuration file in $HOME/.aptitude/config. Otherwise, it will look up the current user's home directory using getpwuid(2) and place its configuration file there.

PAGER

If this environment variable is set, aptitude will use it to display changelogs when “aptitude changelog” is invoked. If not set, it defaults to more.

TMP

If TMPDIR is unset, aptitude will store its temporary files in TMP if that variable is set. Otherwise, it will store them in /tmp.

TMPDIR

aptitude will store its temporary files in the directory indicated by this environment variable. If TMPDIR is not set, then TMP will be used; if TMP is also unset, then aptitude will use /tmp.

## SEE ALSO
apt-get(8), apt(8), /usr/share/doc/aptitude/html/<lang>/index.html from the package aptitude-doc-<lang>

## AUTHOR
Daniel Burrows <dburrows@debian.org>

Author.

## COPYRIGHT
This manual page is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual page is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


aox

package: archiveopteryx

title: aox(8)

text:
# aox(8)

## NAME
aox - management tool for Archiveopteryx.

## SYNOPSIS
/usr/bin/aox verb noun [ options ] [ arguments ]

aox help commands

aox help command

## DESCRIPTION
aox is a command-line program to perform various system administration tasks for Archiveopteryx.

Examples of such tasks are adding users, changing the access control for mailboxes, etc. In principle, everything one would want to do using a shell script should be doable using aox.

## COMMANDS
aox start [-v]

Starts the Archiveopteryx servers in the correct order.

aox stop [-v]

Stops the running Archiveopteryx servers in the correct order.

aox restart [-v]

Restarts the servers in the correct order (currently equivalent to start && stop).

aox show status [-v]

Displays a summary of the running Archiveopteryx servers.

aox show configuration [-p -v] [variable-name]

Displays variables configured in archiveopteryx.conf.

If a variable-name is specified, only that variable is displayed.

The -v flag displays only the value of the variable.

The -p flag restricts the results to variables whose value has been changed from the default.

configuration may be abbreviated as cf.

aox show build

Displays the build settings used for this installation (as configured in Jamsettings).

aox show counts [-f]

Displays the number of rows in the most important tables, as well as the total size of the mail stored.

The -f flag causes it to collect slow-but-accurate statistics. Without it, by default, you get quick estimates (more accurate after VACUUM ANALYSE).

aox show queue

Displays a list of all mail queued for delivery to a smarthost.

aox show schema

Displays the revision of the existing database schema.

aox upgrade schema [-n]

Checks that the database schema is one that this version of Archiveopteryx is compatible with, and updates it if needed.

The -n flag causes aox to perform the SQL statements for the schema upgrade and report on their status without COMMITing the transaction (i.e. see what the upgrade would do, without doing anything).

aox update database

Performs any updates to the database contents which are too slow for inclusion in aox upgrade schema. This command is meant to be used while the server is running. It does its work in small chunks, so it can be restarted at any time, and is tolerant of interruptions.

aox tune database <mostly-writing|mostly-reading|advanced-reading>

Adjusts the database indices and configuration to suit expected usage patterns.

aox list mailboxes [-d] [-o username] [pattern]

Displays a list of mailboxes matching the specified shell glob pattern. Without a pattern, all mailboxes are listed.

The -d flag includes deleted mailboxes in the list.

The "-o username" flag restricts the list to mailboxes owned by the specified user.

The -s flag shows a count of messages and the total size of the messages in each mailbox.

ls is an acceptable abbreviation for list.

aox list users [pattern]

Displays a list of users matching the specified shell glob pattern. Without a pattern, all users are listed.

aox list aliases [pattern]

Displays a list of aliases where either the address or the target mailbox matches the specified shell glob pattern. Without a pattern, all aliases are listed.

aox list rights <mailbox> [username]

Displays a list of users and the rights they have been granted to the specified mailbox. If a username is given, only that user's rights are displayed.

aox add user <username> <password> <email-address>

aox add user -p <username> <email-address>

Creates a new Archiveopteryx user with the specified username, password, and email address. If the -p flag is specified, the password is read interactively, instead of from the command-line.

create and new are acceptable abbreviations for add.

aox delete user [-f] <username>

Deletes the specified Archiveopteryx user. If -f is specified, any mailboxes owned by the user are also deleted.

del and remove are acceptable abbreviations for delete.

aox change password <username> <new-password>

aox change password -p <username>

Changes the specified user's password. If the -p flag is specified, the password is read interactively, instead of from the command-line.

aox change username <username> <new-username>

Renames the specified user.

aox change address <username> <new-address>

Changes the specified user's email address.

aox add mailbox <name> [username]

Creates a new mailbox with the specified name and, if a username is specified, owned by that user.

The mailbox name must be fully-qualified (begin with /), unless a username is specified, in which case unqualified names are assumed to be under the user's home directory.

aox delete mailbox [-f] <name>

Deletes the specified mailbox.

If -f is specified, the mailbox and any messages it contains are permanently deleted. Otherwise, only empty mailboxes are deleted.

aox add view <name> <source> <owner> <search>

Creates a new view mailbox which applies the specified search on the specified source mailbox. When a new message is added to the source, and it matches the search, it will automatically be added to the view as well.

aox add alias <address> <mailbox>

Creates an alias that instructs the server to accept mail to the given address and deliver it to the specified mailbox.

aox delete alias <address>

Deletes an alias, if one exists, for the given address.

aox setacl [-d] <mailbox> <identifier> <rights>

Assigns the specified rights to the given identifier on the mailbox. If the rights begin with + or -, the specified rights are added to or subtracted from the existing rights; otherwise, the rights are set to exactly those given.

With -d, the identifier's rights are deleted altogether.

A summary of the changes made is displayed when the operation completes.

aox undelete <mailbox> <search>

Searches for deleted messages in the specified mailbox and restores those that match the search.

Messages can be restored after an IMAP EXPUNGE or POP3 DELE until aox vacuum permanently removes them after the configured undelete-time.

Example: aox undelete /users/fred/inbox from example.com

aox vacuum

Permanently deletes messages that were marked for deletion more than undelete-time days ago, and removes any bodyparts that are no longer used.

This is not a replacement for running VACUUM ANALYSE on the database (either with vacuumdb or via autovacuum).

This command should be run (we suggest daily) via crontab.

aox anonymise <file>

Reads a mail message from the named file, obscures most or all content and prints the result on stdout. The output resembles the original closely enough to be used in a bug report.

aox reparse

Looks for messages that "arrived but could not be stored" and tries to parse them using workarounds that have been added more recently. If it succeeds, the new message is injected and the old one deleted.

aox grant privileges <username>

makes sure that the named user has all the permissions needed for the db-user (i.e., and unprivileged user), and no more.

aox check config

reads the configuration files and reports any problems that it finds.

## OPTIONS
The -v flag enables (slightly) more verbose diagnostic output wherever it is supported (see the descriptions of each command above).

## EXAMPLES
To add a user called "nirmala", whose password is "angstskrik" and whose main email address is "nirmala@example.com":

aox add user nirmala angstskrik nirmala@example.com

To change Nirmala's password to "temmelig hemmelig":

aox change password nirmala 'temmelig hemmelig'

To remove that user:

aox remove user nirmala

## DIAGNOSTICS
The return code of aox is zero if all goes well, and a non-zero in case of errors.

Diagnostics are logged using Archiveopteryx's logd(8), just like the servers do. Disasters are also logged via stderr.

## BUGS
There is no command-line option to set the configuration file.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), http://archiveopteryx.org


aoximport

title: aoximport(8)

text:
# aoximport(8)

## NAME
aoximport - import messages into Archiveopteryx.

## SYNOPSIS
/usr/bin/aoximport [-vqe] mailbox type source-file [ source-file ... ]

## DESCRIPTION
aoximport is used to import messages into Archiveopteryx en masse from other mailboxes (mbox, MH, maildir and Cyrus mailboxes are currently supported).

## OPTIONS
-v

enables more verbose output. Can be repeated.

-q

sets the verbosity to zero.

-e

makes aoximport write problem messages to the errors subdirectory. If a message has parse problems, aoximport writes a copy of the message to errors/anonymised if anonymisation preserves the error, and to errors/plaintext else. The message is also written to the target mailbox, as an attachment to a special error message.

The messages in the errors directory may be sent to info@aox.org, and we'll try to find out what the problem is. Please delete personal/confidential messages from errors/plaintext first.

## SYNTAX
In the synopsis above, mailbox is the fully-qualified name of the destination mailbox (which must exist) into which messages are imported. type may be mbox, maildir, mh, or cyrus. The remaining arguments are interpreted as mailbox filenames of the specified type.

## EXAMPLES
To import messages from the mbox files in ~/Mail/imap/* to a mailbox named /users/nirmala/imap:

aoximport /users/nirmala/imap mbox ~/Mail/imap/*

After a large import, it's a good idea to run aox vacuum.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
aox(8), archiveopteryx(8), http://archiveopteryx.org


archiveopteryx

title: archiveopteryx(8)

text:
# archiveopteryx(8)

## NAME
Overview of Archiveopteryx.

## SYNOPSIS
/etc/init.d/archiveopteryx {start,stop}

/etc/archiveopteryx/*.conf

## DESCRIPTION
Archiveopteryx is a mail server system optimised for long-term storage and heavy access. It comprises a set of server programs that provide access to mail stored in a relational database (PostgreSQL).

## GETTING STARTED
The following five steps should suffice to install Archiveopteryx. If they don't, or if anything is unclear, more detailed instructions are available at http://archiveopteryx.org/installation

### 1. Install Archiveopteryx
Usually, this is as simple as:

apt-get install archiveopteryx (on Debian)

portinstall archiveopteryx (on FreeBSD)

http://archiveopteryx.org/installation explains what to do in other cases.

Use

/usr/lib64/archiveopteryx/archiveopteryx start

to start Archiveopteryx using the default configuration from archiveopteryx.conf, which tries hard to be sensible.

### 2. Add a user
Run

aox add user name password address@domain

to create a username and password.

### 3. Inject some test mail
You can use deliver(8) to inject some mail you already have.

This command injects all the messages from a berkeley mbox file:

formail -s deliver yourname@domain < mbox

### 4. Check that you can read mail
The mail you just delivered is in your inbox, and you can read it with any IMAP or POP3 client.

### 5. Configure your MTA
The normal way to deliver mail from your MTA into Archiveopteryx is via LMTP. By default, Archiveopteryx listens on 127.0.0.1 port 2026.

On aox.org we describe how to configure some common MTAs to work with Archiveopteryx. See e.g. http://archiveopteryx.org/postfix for postfix(1).

## ARCHITECTURE
Archiveopteryx consists of a number of frontend servers, each of which uses backend servers:

RDBMS

The RDBMS is where all the mail is stored. At present only PostgreSQL is supported.

logd

The log server is an internal server which filters log entries so useful messages are logged while noise is suppressed.

Each server is described more fully in its own man page: logd(8), postgres(1) and archiveopteryx(8) for the frontend server, which serves IMAP, POP3, LMTP and/or SMTP and perhaps webmail.

Normally, there is one logd(8) process running. In addition there will be at least one postgres(1) and one archiveopteryx(8) process.

The servers use TCP to communicate internally, so they can be distributed across a server cluster. Generally, one host will run the database backend, one host (perhaps the same) will run logd(8) and as many as required will run frontends.

The man pages for each server explain the use and configuration of each. See archiveopteryx.conf(5) for more about configuring Archiveopteryx in general.

## SECURITY
All Archiveopteryx servers run in chroot directories.

The user-facing servers run in a special jail directory. They have neither read nor write access to this directory.

logd(8) runs chrooted to another directories. All of the servers close all open files at startup and drop root privileges. By default they run as user aox, group aox, although these names can be changed using archiveopteryx.conf(5).

The servers check that they lose prvileges as expected, and refuse to start if they're too privileged.

Note that logd(8) must have permission to create the logfile.

## MAIL STORAGE
Archiveopteryx does not store mail in the RFC-822 format. It parses each message upon delivery, and stores a normalized representation, optimized for fast and reliable search and categorization.

This offers the following advantages, among others:

Performance

One example: Each address is stored exactly once, as Unicode and with RFC-2047 encoding undone. Finding all messages sent from/to a given name is extremely fast, because only a single SQL SELECT is necessary, and it accesses just two small tables.

Long-term Stability

Archiveopteryx handles today's common syntax problems and stores the correct form in the database. Because of that, the mail reader which looks at old mail in the year 2020 will not need to be bug compatible with today's version of Microsoft Outlook.

Scalability and Flexibility

Only the database size limits Archiveopteryx's capacity. Many other servers limit individual folders to 2GB (or less), or cannot support more than a few thousand subfolders/messages in a folder. With Archiveopteryx, you don't need to invent workarounds for such artificial limitations.

Robustness

Because mail is stored normalized and parsed, large attachments are generally stored only once, and mail parsing exploits are rendered harmless before reaching the MUA. A movie clip sent to a hundred recipients is not a problem, because it's stored just once.

## LICENSING
Archiveopteryx is available under two licences, namely the OSL 3.0 license and a commercial software license.

The OSL 3.0 (see http://archiveopteryx.org/opensource) is a fairly restrictive open source license similar to the more well-known GNU licenses. It includes a disclaimer of responsibility.

Our commercial license offers more flexibility than the OSL and a full warranty. There are also extra services. Contact info@aox.org for more details, or see http://archiveopteryx.org/commercial

## DEFAULTS
The configurable file and directory names in this build are as follows:

SBINDIR

(where servers live) is /usr/sbin.

BINDIR

(where other executables live) is /usr/bin.

INITDIR

(where the startup script lives) is /usr/lib64/archiveopteryx.

MANDIR

(where manpages live) is /usr/share/man.

PIDFILEDIR

(where pidfiles live) is /var/run.

LIBDIR

(where supporting files live) is /usr/lib64/archiveopteryx.

JAILDIR

(the working directory of the user-facing servers) is /var/lib/archiveopteryx, and can be overridden using the jail-directory variable in archiveopteryx.conf(5).

CONFIGDIR

(where the configuration files live) is /etc/archiveopteryx.

LOGFILE

(the full name of the logfile) is syslog/mail, and can be overridden using the logfile variable in archiveopteryx.conf(5).

These variables can be changed only by editing the file Jamsettings and recompiling Archiveopteryx. Jamsettings also contains some variables used only during compilation and/or installation, and some which provide defaults for archiveopteryx.conf(5) settings.

## FILES
/etc/archiveopteryx/archiveopteryx.conf

contains the Archiveopteryx configuration.

/usr/lib64/archiveopteryx/automatic-key.pem

contains a private key and self-signed certificate used by openssl(3).

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), deliver(8), logd(8), http://archiveopteryx.org


deliver

title: deliver(8)

text:
# deliver(8)

## NAME
deliver - deliver mail into Archiveopteryx.

## SYNOPSIS
/usr/bin/deliver [-f sender] [-t mailbox] [-v] destination [filename]

## DESCRIPTION
The deliver program injects a single mail message in RFC-822 format into Archiveopteryx. It connects to Archiveopteryx's backend ddatabase injects the message into the correct mailbox.

deliver is meant as a compatibility shim for use with e.g. formail(1) and with MTAs that want to deliver to a program. Note that you will generally get better performance by using LMTP.

deliver bypasses Sieve and always stores mail directly into the target mailbox.

## OPTIONS
-f sender

specifies the fully qualified address of the message sender. This is the same as the SMTP envelope sender.

Starting with version 2.01, the -f argument is ignored. It is still accepted to keep old scripts working.

-t mailbox

directs deliver to store the message into the named mailbox. The "p" right on the mailbox must be granted to "anyone". ("p" controls who is permitted to send mail to the mailbox, see RFC 4314 for more details.)

-v

requests more verbosity during delivery. May be specified twice.

## EXAMPLES
To deliver an entire berkeley mbox into the inbox of user nirmala@example.com:

formail -s deliver nirmala@example.com < mbox

To deliver each message in the MH folder +blah into the inbox of user raj@example.net:

folder +blah

seq all | xargs -n1 deliver raj@example.net

To deliver each message in the MH folder +ramble into folder stumble of user raj@example.net:

folder +blah

seq all | xargs -n1 deliver -t stumble raj@example.net

If raj has not granted "anyone" the "p" right ("p"ost mail to mailbox), this example fails.

## DIAGNOSTICS
The normal exit status of deliver is 0. In case of errors, deliver returns an error code from sysexits.h, such as EX_TEMPFAIL, EX_NOUSER, etc.

## BUGS
Delivering multiple messages would also be good, for those big mailbox migrations. In that case, deliver should report which messages could be delivered and which could not.

There is no command-line option to set the configuration file.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), logd(8), http://archiveopteryx.org


installer

title: installer(8)

text:
# installer(8)

## NAME
installer - Archiveopteryx installer.

## SYNOPSIS
/usr/lib64/archiveopteryx/installer [ -n ] [ -q ] [ -v ] ...

## DESCRIPTION
This program does the following:

1. Creates a Unix group named aox.

2. Creates a Unix user named aox.

3. Creates a Postgres user named aox.

4. Creates a Postgres user named aoxsuper.

5. Creates a Postgres database named archiveopteryx owned by aoxsuper.

6. Loads the database schema and grants limited privileges to user aox.

7. Generates an initial configuration file.

8. Adjusts ownership and permissions if necessary.

installer should be run after jam install when installing from source.

By default, the address of the PostgreSQL server is derived from the compile-time DBADDRESS setting in the Jamsettings file (which is 127.0.0.1 by default). If the db-address variable is set in an existing configuration file, that value takes precedence. If the -a command-line flag is used, then the address specified has precedence over either of the former values.

If the server address (as determined above) is 127.0.0.1, the installer will try to use a Unix domain socket to connect to the server. The location of this socket is determined by the -s socket command-line argument. If no socket is specified, the default named socket location ( /tmp/.s.PGSQL.5432) is used instead. For any other server address, the installer will try to use a Unix domain socket only if one is explicitly specified with -s. In any case, if password authentication is to be used when talking to the server, the -P option will cause the installer to prompt for the password.

## OPTIONS
-q

Suppresses all normal output.

-v

Makes the output more verbose (may be repeated).

-n

Causes the program to report what it would do, but not actually do anything.

-g group

Allows you to specify a Unix group other than the default of aox.

-u user

Allows you to specify a Unix username other than the default of aox.

-p postgres

Allows you to specify the name of the PostgreSQL superuser. The default is to try $PGUSER (if set), postgres and pgsql in turn.

-P

Instructs the installer to prompt for and read the PostgreSQL superuser's password, and be prepared to use that for authentication (if necessary).

-a address

Allows you to specify a different address for the Postgres server. The default is 127.0.0.1.

-s /path/to/socket

Allows you to specify a location for the PostgreSQL server's Unix-domain listening socket. The specified value is used as described above.

-t port

Allows you to specify a different port for the Postgres server. The default is 5432. (This value is used only if the server address does not refer to a Unix socket.)

-d dbname

Allows you to specify a database to use. The default is archiveopteryx.

-S schema

Allows you to specify a schema where the Archiveopteryx database objects will be installed. If this is not specified, objects are installed into the public schema.

Please do not use -S unless you are sure you understand all its implications. It is safe to ignore it entirely if you don't.

The defaults come from Jamsettings.

## DIAGNOSTICS
The return code is zero if all goes well, and a non-zero in case of errors. Disasters are logged via stderr.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), logd(8), http://archiveopteryx.org


logd

title: logd(8)

text:
# logd(8)

## NAME
logd - logging server for Archiveopteryx.

## SYNOPSIS
/usr/sbin/logd [-f] [-c configfile]

## DESCRIPTION
The Archiveopteryx logd is an internal server which receives, buffers and filters log entries from other parts of Archiveopteryx, so that useful messages are logged, while noise is suppressed.

Archiveopteryx's log system uses four log levels: Disaster, Error, Info and Debug. Each program in Archiveopteryx sends its log messages to logd, which writes them to a logfile.

If a message is logged with severity log-level (set to Info by default) or greater, it is immediately written to the log file. All messages of lower severity are discarded.

If logd receives the SIGHUP signal, it closes and reopens its logfile.

After startup, logd changes root to the directory where logfile is located, and changes uid and gid to jail-user and jail-group. Therefore, jail-user must have the right to open logfile.

## OPTIONS
-c filename

Read configuration variables from filename instead of from /etc/archiveopteryx/archiveopteryx.conf.

-f

Fork into background during startup.

## CONFIGURATION
logd is configured using archiveopteryx.conf(5).

logd uses the following configuration variables: log-address, log-port, logfile (default syslog/mail), log-level (default info), jail-user (default aox), jail-group (default aox).

## DIAGNOSTICS
In case of error, smtpd exits with exit code 1, an error message on stderr and (usually more detailed) information in the log file.

## FILES
/etc/archiveopteryx/archiveopteryx.conf

/usr/sbin/logd

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), deliver(8), aox(8), http://archiveopteryx.org


recorder

title: recorder(8)

text:
# recorder(8)

## NAME
recorder - IMAP connection recorder

## SYNOPSIS
/usr/sbin/recorder srcport address destport file

## DESCRIPTION
The recorder program relays data between an IMAP client and server, and records the session in a format which allows the Archiveopteryx developers to replay and analyse it later.

If you have problems getting archiveopteryx(8) to work with a particular IMAP client, you can make the client connect to the recorder, instead of directly to imapd, and recorder will produce a transcript of the IMAP session. If the client opens more than one connection, recorder stores more than one file.

The file format is pure ASCII and can be edited. We suggest that you edit out your password, then send the rest to info@aox.org and we may be able to find out what's happening.

We have debug tools that can replay the connection, so we can fix any bugs on the server's side. In some cases, we can also add the file to our regression tests, so we can be sure that new versions of archiveopteryx(8) do not have the same error.

## EXAMPLE
To intercept and record traffic to the IMAP server on 192.0.2.17 and place a record of the connections in files called /tmp/bugreport* you can do the following:

### Disable TLS
recorder does not work when TLS is being used. (To TLS, a tool like recorder looks like a man-in-the-middle attack.)

To disable TLS, set the variable use-tls to disabled in /etc/archiveopteryx/archiveopteryx.conf (see the archiveopteryx.conf(5) man page for more information.)

### Restart Archiveopteryx
The change to use-tls only takes effect when you restart Archiveopteryx, e.g. by issuing the following command:

/usr/lib64/archiveopteryx/archiveopteryx restart

### Start recorder
To make recorder listen on port 1430 and forward connections to the real server on port 143:

/usr/sbin/recorder 1430 192.0.2.17 143 /tmp/bugreport

### Connect to recorder
With the IMAP client, you connect to port 1430 on this host instead of the real server, and work as usual. Please don't do much more than is necessary to reproduce the problem, because it makes the bugreport files grow very large.

Stop

Just hit Control-C to stop recorder when you're done. The files called /tmp/bugreport* contain the IMAP session transcripts.

Remove passwords

Please edit the files to remove any passwords or other confidential data. If you can, don't change the number of words or bytes. It's best to change all the letters in passwords and confidential words to 'x'.

That's it. Now you can send an excellent bug report to info@aox.org.

## AUTHOR
The Archiveopteryx Developers, info@aox.org.

## VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://archiveopteryx.org/3.1.3

## SEE ALSO
archiveopteryx(8), archiveopteryx.conf(5), deliver(8), logd(8), http://archiveopteryx.org


title: arping2(8)

text:
# arping2(8)

## NAME
arping - sends arp and/or ip pings to a given host

## SYNOPSIS
arping [-0aAbBdDeFhpqrRuUv] [-S host/ip] [-T host/ip] [-s MAC] [-t MAC] [-c count] [-i interface] [ -w seconds ] [ -W seconds ] [ -V vlan ] [ -Q priority ] [ -g group ] <host | -B>

arping --help

## DESCRIPTION
The arping utility sends ARP and/or ICMP requests to the specified host and displays the replies. The host may be specified by its hostname, its IP address, or its MAC address.

One request is sent each second.

When pinging an IP an ARP who-has query is sent. When pinging a MAC address a directed broadcast ICMP Echo request is sent. For more technical explanation and an FAQ, see the README file.

Note on timing

ARP packets are usually replied to (on a LAN) so fast that the OS task scheduler can’t keep up to get exact enough timing. On an idle system the roundtrip times will be pretty much accurate, but with more load the timing gets less exact.

To get more exact timing on a non-idle system, re-nice arping to -15 or so.

\# nice -n -15 arping foobar

This is not just an issue with arping, it is with normal ping also (at least it is on my system). But it doesn’t show up as much with ping since arping packets (when pinging IP) doesn’t traverse the IP stack when received and are therefore replied to faster.

## OPTIONS
--help

Show extended help. Not quite as extensive as this manpage, but more than -h.

-0

Use this option to ping with source IP address 0.0.0.0. Use this when you haven’t configured your interface yet. Note that this may get the MAC-ping unanswered. This is an alias for -S 0.0.0.0.

-a

Audible ping.

-A

Only count addresses matching requested address (This *WILL* break most things you do. Only useful if you are arpinging many hosts at once. See arping-scan-net.sh for an example).

-b

Like -0 but source broadcast source address (255.255.255.255). Note that this may get the arping unanswered since it’s not normal behavior for a host.

-B

Use instead of host if you want to address 255.255.255.255.

-c count

Only send count requests.

-C count

Only wait for count replies, regardless of -c and -w.

-d

Find duplicate replies. Exit with 1 if there are answers from two different MAC addresses.

-D

Display answers as exclamation points and missing packets as dots. Like flood ping on a Cisco.

-e

Like -a but beep when there is no reply.

-F

Don’t try to be smart about the interface name. Even if this switch is not given, -i disables this smartness.

-g group

setgid() to this group instead of the nobody group.

-h

Displays a help message and exits.

-i interface

Don’t guess, use the specified interface.

-m type

Type of timestamp to use for incoming packets. Use -vv when pinging to list available ones.

-p

Turn on promiscious mode on interface, use this if you don’t "own" the MAC address you are using.

-P

Send ARP replies instead of requests. Useful with -U.

-q

Does not display messages, except error messages.

-Q priority

802.1p priority to set. Should be used with 802.1Q tag (-V). Defaults to 0.

-r

Raw output: only the MAC/IP address is displayed for each reply.

-R

Raw output: Like -r but shows "the other one", can be combined with -r.

-s MAC

Set source MAC address. You may need to use -p with this.

-S IP

Like -b and -0 but with set source address. Note that this may get the arping unanswered if the target does not have routing to the IP. If you don’t own the IP you are using, you may need to turn on promiscious mode on the interface (with -p). With this switch you can find out what IP-address a host has without taking an IP-address yourself.

-t MAC

Set target MAC address to use when pinging IP address.

-T IP

Use -T as target address when pinging MACs that won’t respond to a broadcast ping but perhaps to a directed broadcast.

Example:

```
To check the address of MAC-A, use knowledge of MAC-B and IP-B.
```

```
$ arping -S <IP-B> -s <MAC-B> -p <MAC-A>
```

-u

```
Show index=received/sent instead of just index=received when
pinging MACs.
```

-U

```
Send unsolicited ARP. This sets the destination MAC address in
the ARP frame to the broadcast address. Unsolicited ARP is used
to update the neighbours’ ARP caches.
```

```
Example:

$ arping -i <interface> -U <interface IP>
```

-v

```
Verbose output. Use twice for more messages.
```

-V vlan

```
VLAN tag to set. Defaults to no VLAN tag.
```

-w sec

```
Specify a timeout before ping exits regardless of how many packets have been sent or received.
```

-W sec

```
Time to wait between pings.
```

-z

```
Enable seccomp (default seccomp state depends on compile options)
```

-Z

```
Disable seccomp (default seccomp state depends on compile options)
```

## EXAMPLES

```
# arping -c 3 88.1.180.225
ARPING 88.1.180.225
60 bytes from 00:11:85:4c:01:01 (88.1.180.225): index=0 time=13.910 msec
60 bytes from 00:11:85:4c:01:01 (88.1.180.225): index=1 time=13.935 msec
60 bytes from 00:11:85:4c:01:01 (88.1.180.225): index=2 time=13.944 msec
```

```
--- 88.1.180.225 statistics ---
3 packets transmitted, 3 packets received,   0% unanswered
```

```
# arping -c 3 00:11:85:4c:01:01
ARPING 00:11:85:4c:01:01
60 bytes from 88.1.180.225 (00:11:85:4c:01:01): icmp_seq=0 time=13.367 msec
60 bytes from 88.1.180.225 (00:11:85:4c:01:01): icmp_seq=1 time=13.929 msec
60 bytes from 88.1.180.225 (00:11:85:4c:01:01): icmp_seq=2 time=13.929 msec
```

```
--- 00:11:85:4c:01:01 statistics ---
3 packets transmitted, 3 packets received,   0% unanswered
```

```
# arping -C 2 -c 10 -r 88.1.180.225
00:11:85:4c:01:01
00:11:85:4c:01:01
```

```

```

## BUGS
You have to use -B instead of arpinging 255.255.255.255, and -b instead of -S 255.255.255.255. This is libnets fault.

## SEE ALSO
ping(8), arp(8), rarp(8)

## AUTHOR
Arping was written by Thomas Habets <thomas@habets.se>.

http://www.habets.pp.se/synscan/

git clone http://github.com/ThomasHabets/arping.git


arpsend

package: arpsend

title: arpsend(8)

text:
# arpsend(8)

## NAME
arpsend - send an Ethernet frame containing an IP ARP request or reply packet with user-specified fields

## SYNOPSIS
arpsend [ -c count ] [ -d debuglevel ] [ -h ] [ -p pause_time ] [ -q ] [ -v ] [ -w ]

[ -i interface_name ]

[ -E ether_source_address ] [ -e ether_dest_address ]

[ -Q vlan_id ]

[ -o arp_opcode ]

[ -S sender_hardware_address ] [ -s sender_protocol_address ]

[ -T target_hardware_address ] -t target_protocol_address

## DESCRIPTION
arpsend sends an Ethernet frame containing an IP ARP request or reply packet containing fields you specify. This is a diagnostic tool intended for use by network administrators.

The program does not listen for any ARP replies; if you want to see any ARP replies prompted by a request, you should use another program to do so, such as tcpdump(1).

## AVAILABILITY
arpsend is a product of the Network Switching and Routing at Princeton University's Office of Information Technology, and is available from https://www.net.princeton.edu/software/arpsend/

Presently the product builds and runs on Solaris 9 and 10 on SPARC with gcc.

The program relies on the libnet(3) library.

## OPTIONS
-c count

Specifies the number of packets to send. If not specified, this defaults to 1.

-d debug_level

Sets the debug_level variable that controls the amount of debugging messages generated. If not specified, this defaults to 0 (no debugging). Presently no debugging messages are defined.

-E ether_source_address

Specifies the source address of the Ethernet frame. If not specified, this defaults to the Ethernet address of the outgoing interface. (Some environments may not allow you to override this value.)

-e ether_dest_address

Specifies the destination address of the Ethernet frame. If not specified, this defaults to the Ethernet broadcast address.

-h

Display a brief usage summary, then exit.

-i interface_name

Specifes the name of the Ethernet interface through which the packet should be sent. If not specified, this defaults to the first interface that is up (other than loopback).

-o arp_opcode

Specifies the ARP opcode; valid values are 1 (ARP Request) and 2 (ARP Reply). If not specified, this defaults to 1 (ARP Request).

-p pause_time

Specifies the number of seconds to pause between sending each packet, when the packet count is great than 1. If not specified, this defaults to 1 second.

-q

Specifies 'quiet' operation; only errors and warnings are displayed.

-Q vlan_id

Tag the frame with an 802.1Q VLAN ID.

-S sender_hardware_address

Specifies the ARP sender hardware address. If not specified, this defaults to the Ethernet address of the outgoing interface.

-s sender_protocol_address

Specifies the ARP sender protocol address. If not specified, this defaults to the primary IP address of the outgoing interface.

-T target_hardware_address

Specifies the ARP target hardware address. If not specified, this default to 0:0:0:0:0:0.

-t target_protocol_address

Specifies the ARP target protocol address. This option must be specified; no default value is supplied.

-v

Display the program's version number, then exit.

-w

Specifies that arpsend should not warn you about values that might cause network problems.

## OPERATION
arpsend is a diagnostic tool intended to be used by an network administrator. It is possible to specify values that will interfere with the normal operation of devices attached to the network, or the network as a whole.

arpsend checks for the most-common values that could cause network problems, but by no means can catch all such combinations of values. When it believes the values you specify could cause a problem, it will display a warning, and ask you if you still wish to send the packet. You can skip these checks (and the associated prompt) with the -w option; your packet will be sent without comment.

## EXAMPLES
To broadcast an ARP Request out the first interface that is up, requesting that 192.168.1.1 respond with an ARP Reply:

```
arpsend -t 192.168.1.1
```

In the example above, if my own IP address (on this interface) were 192.168.1.1, the packet would be a Gratuitous ARP request. Although the value of the target hardware address is not significant in a Gratuitous ARP request, typical ARP implementations set it to ff:ff:ff:ff:ff:ff when they send a Gratuitous ARP request; you can duplicate this behavior with:

```
arpsend -T ff:ff:ff:ff:fff:ff -t 192.168.1.1
```

To unicast an ARP Request via interface le1 to 0:0:1:1:2:3, requesting that 192.168.1.1 respond with an ARP Reply:

```
arpsend -i le1 -e 0:0:1:1:2:3 -t 192.168.1.1
```

To send an ARP Reply that appears to come from a device with IP address 192.168.1.3 and Ethernet address 0:0:1:1:1:1, unicasting the packet to 0:0:1:9:9:9 (we'll pretend that the target device's IP address is 192.168.1.4):

```
arpsend -o 2 -E 0:0:1:1:1:1 -e 0:0:1:9:9:9 -S 0:0:1:1:1:1 -s 192.168.1.3 -T 0:0:1:9:9:9 -t 192.168.1.4
```

## AUTHOR
The program was written by Irwin Tillman of Princeton University OIT Network Switching and Routing. It was written to run on Solaris 9 and 10, relying on the generally-available libnet(3) library.

## SEE ALSO
RFC 826

Address Resolution Protocol

RFC 1122

Host Network Requirements (Link Layer: Specific Issues, section 2.3)

libnet(3)

available from https://codedocs.xyz/libnet/libnet/md_README.html or https://github.com/libnet/libnet/releases


package: asterisk

title: astdb2bdb(8)

summary: convert astdb back to Berkeley DB 1.86

text:
# astdb2bdb(8)

## NAME
astdb2bdb - convert astdb back to Berkeley DB 1.86

## SYNOPSIS
cd astvarlibdir && astdb2bdb path/to/astdb.sqlite3

## DESCRIPTION
Up until version version 11, Asterisk used an old version of the Berkeley DB 1.86 (bdb) to store its internal persistent database. In version 11 it switched to using a SQLIte 3 database. This program is used to convert the newly-formatted SQLite 3 astdb back to bdb.

You may need it in case of reverting an upgrade or other similar scenarios.

## OPTIONS
There is a single (and required) parameter: the path the the sqlite file. The output file will be a file called astdb in the current working directory.

## EXAMPLES
In case you want to revert an upgrade to Asterisk 11, you can do the following (while Asterisk is not running):

cd /var/lib/asterisk && astdb2bdb astdb.sqlite3 && rm astdb.sqlite3

This will convert the newly-formatted astdb back to the old format, and delete it (to avoid obsolete data copies).

## NOTES
Berkeley DB 1.86 is obsolete. It is incompatible with newer versions (4.x and newer) that you may see around. Chances are you don't have the tools to use it independently of Asterisk.

## SEE ALSO
astdb2sqlite3(8), asterisk(8)

## AUTHOR
astdb2bdb was written by Terry Wilson <twilson@digium.com>.

This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>.


title: astdb2sqlite3(8)

summary: convert astdb to SQLite 3

text:
# astdb2sqlite3(8)

## NAME
astdb2sqlite3 - convert astdb to SQLite 3

## SYNOPSIS
astdb2sqlite3 path/to/astdb

## DESCRIPTION
Up until version version 11, Asterisk used an old version of the Berkeley DB 1.86 (bdb) to store its internal persistent database. In version 11 it switched to using a SQLite 3 database. This program is used to convert an existing bdb astdb file to astdb.sqlite3.

Normally the conversion is done by Asterisk itself which will run this program. But you may need to run it on your own.

## OPTIONS
There is a single (and required) parameter: the path the the bdb file. The output file name will be the same as the input, with .sqlite3 appended.

## EXAMPLES
Asterisk will typically run the following to upgrade the database:

astdb2sqlite3 /var/lib/asterisk/astdb

which will create /var/lib/asterisk/astdb.sqlite3.

## SEE ALSO
astdb2bdb(8), asterisk(8)

## AUTHOR
astdb2sqlite3 was written by Terry Wilson <twilson@digium.com>.

This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>.


asterisk

title: asterisk(8)

summary: All-purpose telephony server.

text:
# asterisk(8)

## NAME
asterisk - All-purpose telephony server.

## SYNOPSIS

asterisk

[-BcdfFghiImnpqRtTvVW] [-C file] [-e memory] [-G group] [-L loadaverage] [-M value] [-U user] [-s socket-file]

asterisk -r

[-v] [-d] [-x command]

asterisk -R

[-v] [-d] [-x command]

## DESCRIPTION
asterisk is a full-featured telephony server which provides Private Branch eXchange (PBX), Interactive Voice Response (IVR), Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, Conferencing, and a plethora of other telephony applications to a broad range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny, H.323, Unistim) devices (both endpoints and proxies), as well as traditional TDM hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart, ISDN BRI and many more.

At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration file and locates the rest of the configuration files from the configuration in that file. The -C option specifies an alternate main configuration file. Virtually all aspects of the operation of asterisk's configuration files can be found in the sample configuration files. The format for those files is generally beyond the scope of this man page.

When running with -c, -r or -R options, Asterisk supplies a powerful command line, including command completion, which may be used to monitors its status, perform a variety of administrative actions and even explore the applications that are currently loaded into the system.

Asterisk is a trademark of Digium, Inc.

## OPTIONS
Running Asterisk starts the asterisk daemon (optionally running it in the foreground). However running it with -r or -R connects to an existing Asterisk instance through a remote console.

-B

Force the background of the terminal to be black, in order for terminal colors to show up properly. Equivalent to forceblackbackground = yes in asterisk.conf. See also -n and -W.

-C file

Use file as master configuration file instead of the default, /etc/asterisk/asterisk.conf

-c

Provide a control console on the calling terminal. The console is similar to the remote console provided by -r. Specifying this option implies -f and will cause asterisk to no longer fork or detach from the controlling terminal. Equivalent to console = yes in asterisk.conf.

-d

Enable extra debugging statements. This parameter may be used several times, and each increases the debug level. Equivalent to debug = num in asterisk.conf to explicitly set the initian debug level to num. When given at startup, this option also implies -f (no forking). However when connecting to an existing Asterisk instance (-r or -R), it may only increase the debug level.

-e memory

Limit the generation of new channels when the amount of free memory has decreased to under memory megabytes. Equivalent to minmemfree = memory in asterisk.conf.

-f

Do not fork or detach from controlling terminal. Overrides any preceding specification of -F on the command line. Equivalent to nofork = yes in asterisk.conf. See also -c.

-F

Always fork and detach from controlling terminal. Overrides any preceding specification of -f on the command line. May also be used to prevent -d and -v to imply no forking. Equivalent to alwaysfork = yes in asterisk.conf.

-g

Remove resource limit on core size, thus forcing Asterisk to dump core in the unlikely event of a segmentation fault or abort signal. NOTE: in some cases this may be incompatible with the -U or -G flags.

-G group

Run as group group instead of the calling group. NOTE: this requires substantial work to be sure that Asterisk's environment has permission to write the files required for its operation, including logs, its comm socket, the asterisk database, etc.

-h

Provide brief summary of command line arguments and terminate.

-i

Prompt user to intialize any encrypted private keys for IAX2 secure authentication during startup.

-I

Enable internal timing if DAHDI timing is available. The default behaviour is that outbound packets are phase locked to inbound packets. Enabling this switch causes them to be locked to the internal DAHDI timer instead.

-L loadaverage

Limits the maximum load average before rejecting new calls. This can be useful to prevent a system from being brought down by terminating too many simultaneous calls.

-m

Temporarily mutes output to the console and logs. To return to normal, use logger mute.

-M value

Limits the maximum number of calls to the specified value. This can be useful to prevent a system from being brought down by terminating too many simultaneous calls.

-n

Disable ANSI colors even on terminals capable of displaying them. This option can be used only at startup (e.g. not with remote console).

-p

If supported by the operating system (and executing as root), attempt to run with realtime priority for increased performance and responsiveness within the Asterisk process, at the expense of other programs running on the same machine. Note: astcanary will run concurrently with asterisk. If astcanary stops running or is killed, asterisk will slow down to normal process priority, to avoid locking up the machine.

-q

Reduce default console output when running in conjunction with console mode (-c).

-r

Instead of running a new Asterisk process, attempt to connect to a running Asterisk process and provide a console interface for controlling it.

-R

Much like -r. Instead of running a new Asterisk process, attempt to connect to a running Asterisk process and provide a console interface for controlling it. Additionally, if connection to the Asterisk process is lost, attempt to reconnect for as long as 30 seconds.

-s socket file name

In combination with -r, connect directly to a specified Asterisk server socket.

-t

When recording files, write them first into a temporary holding directory, then move them into the final location when done.

-T

Add timestamp to all non-command related output going to the console when running with verbose and/or logging to the console.

-U user

Run as user user instead of the calling user. NOTE: this requires substantial work to be sure that Asterisk's environment has permission to write the files required for its operation, including logs, its comm socket, the asterisk database, etc.

-v

Increase the level of verboseness on the console. The more times -v is specified, the more verbose the output is. Specifying this option implies -f and will cause asterisk to no longer fork or detach from the controlling terminal. This option may also be used in conjunction with -r and -R. Note: This always sets the verbose level in the asterisk process, even if it is running in the background. This will affect the size of your log files.

-V

Display version information and exit immediately.

-W

Display colored terminal text as if the background were white or otherwise light in color. Normally, terminal text is displayed as if the background were black or otherwise dark in color.

-x command

Connect to a running Asterisk process and execute a command on a command line, passing any output through to standard out and then terminating when the command execution completes. Implies -r when -R is not explicitly supplied.

-X

Enables executing of includes via #exec directive inside asterisk.conf.

## EXAMPLES
asterisk - Begin Asterisk as a daemon

asterisk -vvvgc - Run on controlling terminal

asterisk -rx "core show channels" - Display channels on running server

## BUGS
Bug reports and feature requests may be filed at https://github.com/asterisk/asterisk/issues/

## SEE ALSO
https://www.asterisk.org - The Asterisk Home Page

http://www.asteriskdocs.org - The Asterisk Documentation Project

https://docs.asterisk.org - The Asterisk documentation

https://www.digium.com/ - Asterisk is sponsored by Digium

## AUTHOR
Mark Spencer <markster@digium.com>

Countless other contributors, see CREDITS with distribution for more information.


astgenkey

title: astgenkey(8)

text:
# astgenkey(8)

## NAME
astgenkey - generates keys for for Asterisk IAX2 RSA authentication

## SYNOPSIS
astgenkey [ -q ] [ -n ] [ keyname ]

## DESCRIPTION
astgenkey This script generates an RSA private and public key pair in PEM format for use by Asterisk. The private key should be kept a secret, as it can be used to fake your system's identity. Thus by default (without the option -n ) the script will create a passphrase-encrypted copy of your secret key: without entering the passphrase you won't be able to use it.

However if you want to use such a key with Asterisk, you'll have to start it interactively, because the scripts that start asterisk can't use that encrypted key.

The key is identified by a name. If you don't write the name on the command-line you'll be prompted for one. The outputs of the script are:

name.pub

The public key: not secret. Send this to the other side.

name.key

The private key: secret.

Those files should be copied to /var/lib/asterisk/keys

(The private key: on your system. The public key: on other systems)

To see the currently-installed keys from the asterisk CLI, use the command

keys show

## OPTIONS
-q

Run quietly.

-n

Don't encrypt the private key.

## SECURITY
The keys are created, using the umask of the user running the command. To create the keys in a secure manner, you should check to ensure that your umask is first set to disallow the private key from being world- readable, such as with the following commands:

umask 0066

astgenkey yourkey

And then make the key accessible to Asterisk (assuming you run it as user "asterisk").

chown asterisk /var/lib/asterisk/keys/yourname.*

## FILES
/var/lib/asterisk/keys

## SEE ALSO
asterisk(8), genrsa(1), rsa(1),

http://www.voip-info.org/wiki-Asterisk+iax+rsa+auth

## AUTHOR
This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.