sane

package: sane

title: sane(7)

text:
# sane(7)

## NAME
sane - Scanner Access Now Easy: API for accessing scanners

## DESCRIPTION
SANE is an application programming interface (API) that provides standardized access to any raster image scanner hardware. The standardized interface makes it possible to write just one driver for each scanner device instead of one driver for each scanner and application.

While SANE is primarily targeted at a UNIX environment, the standard has been carefully designed to make it possible to implement the API on virtually any hardware or operating system.

This manual page provides a summary of the information available about SANE.

If you have trouble getting your scanner detected, read the PROBLEMS section.

## TERMINOLOGY
An application that uses the SANE interface is called a SANE frontend. A driver that implements the SANE interface is called a SANE backend. A meta backend provides some means to manage one or more other backends.

## SOFTWARE PACKAGES
The package sane-backends contains backends, documentation, networking support, and the command line frontend scanimage(1). The frontends xscanimage(1), xcam(1), and scanadf(1) are included in the package sane-frontends. Both packages can be downloaded from the SANE homepage (http://www.sane-project.org/). Information about other frontends and backends can also be found on the SANE homepage.

## GENERAL INFORMATION
The following sections provide short descriptions and links to more information about several aspects of SANE. A name with a number in parenthesis (e.g. sane-dll(5)) points to a manual page. In this case man 5 sane-dll will display the page. Entries like /usr/share/doc/sane-backends/README are references to text files that were copied to the SANE documentation directory (/usr/share/doc/sane-backends/) during installation. Everything else is a URL to a resource on the web.

SANE homepage

Information on all aspects of SANE including a tutorial and a link to the SANE FAQ can be found on the SANE homepage: http://www.sane-project.org/.

SANE device lists

The SANE device lists contain information about the status of SANE support for a specific device. If your scanner is not listed there (either supported or unsupported), please contact us. See section HOW CAN YOU HELP SANE for details. There are lists for specific releases of SANE, for the current development version and a search engine: http://www.sane-project.org/sane-supported-devices.html. The lists are also installed on your system at /usr/share/doc/sane-backends/.

SANE mailing list

There is a mailing list for the purpose of discussing the SANE standard and its implementations: sane-devel. Despite its name, the list is not only intended for developers, but also for users. There are also some more lists for special topics. However, for users, sane-devel is the right list. How to subscribe and unsubscribe: http://www.sane-project.org/mailing-lists.html.

SANE IRC channel

The IRC (Internet Relay Chat) channel #sane can be found on the Freenode network (irc.libera.chat). It's for discussing SANE problems, talking about development and general SANE related chatting. Before asking for help, please read the other documentation mentioned in this manual page. The channel's topic is also used for announcements of problems with SANE infrastructure (mailing lists, web server, etc.).

Compiling and installing SANE

Look at /usr/share/doc/sane-backends/README and the os-dependent README files for information about compiling and installing SANE.

SCSI configuration

For information about various systems and SCSI controllers see sane-scsi(5).

USB configuration

For information about USB configuration see sane-usb(5).

## FRONTENDS AND MISCELLANEOUS PROGRAMS
scanimage

Command-line frontend. See scanimage(1).

saned

SANE network daemon that allows remote clients to access image acquisition devices available on the local host. See saned(8).

sane-find-scanner

Command-line tool to find SCSI and USB scanners and determine their UNIX device files. See sane-find-scanner(1).

Also, have a look at the sane-frontends package (which includes xscanimage(1), xcam(1), and scanadf(1)) and the frontend information page at http://www.sane-project.org/sane-frontends.html.

## BACKENDS FOR SCANNERS
abaton

Supports Abaton flatbed scanners such as the Scan 300/GS (8bit, 256 levels of gray) and the Scan 300/S (black and white, untested). See sane-abaton(5) for details.

agfafocus

Supports AGFA Focus scanners and the Siemens S9036 (untested). See sane-agfafocus(5) for details.

apple

Supports Apple flatbed scanners including the following scanners: AppleScanner, OneScanner and ColorOneScanner. See sane-apple(5) for details.

artec

Supports several Artec/Ultima SCSI flatbed scanners as well as the BlackWidow BW4800SP and the Plustek 19200S. See sane-artec(5) for details.

artec_eplus48u

Supports the Artec E+ 48U scanner and re-badged models like Tevion MD 9693, Medion MD 9693, Medion MD 9705 and Trust Easy Webscan 19200. See sane-artec_eplus48u(5) for details.

as6e

Supports the Artec AS6E parallel port interface scanner. See sane-as6e(5) for details.

avision

Supports several Avision based scanners including the original Avision scanners (like AV 630, AV 620, ...) as well as the HP ScanJet 53xx and 74xx series, Fujitsu ScanPartner, some Mitsubishi and Minolta film-scanners. See sane-avision(5) for details.

bh

Supports Bell+Howell Copiscan II series document scanners. See sane-bh(5) for details.

canon

Supports the CanoScan 300, CanoScan 600, and CanoScan 2700F SCSI flatbed scanners. See sane-canon(5) for details.

canon630u

Supports the CanoScan 630u and 636u USB scanners. See sane-canon630u(5) for details.

canon_dr

Supports the Canon DR-Series ADF SCSI and USB scanners. See sane-canon_dr(5) for details.

canon_lide70

Supports the CanoScan LiDE 70 and 600 USB scanners. See sane-canon_lide70(5) for details.

canon_pp

Supports the CanoScan FB330P, FB630P, N340P and N640P parallel port scanners. See sane-canon_pp(5) for details.

cardscan

Support for Corex Cardscan USB scanners. See sane-cardscan(5) for details.

coolscan coolscan2 coolscan3

Supports Nikon Coolscan film-scanners. See sane-coolscan(5), sane-coolscan2(5) and sane-coolscan3(5) for details.

epjitsu

Supports Epson-based Fujitsu USB scanners. See sane-epjitsu(5) for details.

epson

Old driver for Epson SCSI, parallel port and USB flatbed scanners. See sane-epson(5) for details but try epson2 first.

epson2

Newer driver for Epson SCSI, parallel port, network and USB flatbed scanners (try this before epson which is outdated). See sane-epson2(5) for details.

escl

Supports scanners through the eSCL protocol. See sane-escl(5) for details.

fujitsu

Supports most Fujitsu SCSI and USB, flatbed and adf scanners. See sane-fujitsu(5) for details.

genesys

Supports several scanners based on the Genesys Logic GL646, GL841, GL843, GL847 and GL124 chips like the Medion 6471 and Hewlett-Packard 2300c. See sane-genesys(5) for details.

gt68xx

Supports scanners based on the Grandtech GT-6801 and GT-6816 chips like the Artec Ultima 2000 and several Mustek BearPaw CU and TA models.

Some Genius, Lexmark, Medion, Packard Bell, Plustek, and Trust scanners are also supported. See sane-gt68xx(5) for details.

hp

Supports Hewlett-Packard ScanJet scanners which utilize SCL (Scanner Control Language by HP). See sane-hp(5) for details.

hpsj5s

Supports the Hewlett-Packard ScanJet 5S scanner. See sane-hpsj5s(5) for details.

hp3500

Supports the Hewlett-Packard ScanJet 3500 series. See sane-hp3500(5) for details.

hp3900

Supports the Hewlett-Packard ScanJet 3900 series. See sane-hp3900(5) for details.

hp4200

Supports the Hewlett-Packard ScanJet 4200 series. See sane-hp4200(5) for details.

hp5400

Supports the Hewlett-Packard ScanJet 54XXC series. See sane-hp5400(5) for details.

hpljm1005

Supports the Hewlett-Packard LaserJet M1005 scanner. See sane-hpljm1005(5) for details.

hs2p

Supports the Ricoh IS450 family of SCSI scanners. See sane-hs2p(5) for details.

ibm

Supports some IBM and Ricoh SCSI scanners. See sane-ibm(5) for details.

kodak

Supports some large Kodak scanners. See sane-kodak(5) for details.

kodakaio

Supports Kodak AiO printer/scanners. See sane-kodakaio(5) for details.

kvs1025

Supports Panasonic KV-S102xC scanners. See sane-kvs1025(5) for details.

leo

Supports the LEO S3 and the Across FS-1130, which is a re-badged LEO FS-1130 scanner. See sane-leo(5) for details.

lexmark

Supports the Lexmark X1100 series of USB scanners. See sane-lexmark(5) for details.

ma1509

Supports the Mustek BearPaw 1200F USB flatbed scanner. See sane-ma1509(5) for details.

magicolor

Supports the KONICA MINOLTA magicolor 1690MF multi-function printer/scanner/fax. See sane-magicolor(5) for details.

matsushita

Supports some Panasonic KVSS high speed scanners. See sane-matsushita(5) for details.

microtek

Supports "second generation" Microtek scanners with SCSI-1 command set. See sane-microtek(5) for details.

microtek2

Supports some Microtek scanners with a SCSI-2 command set. See sane-microtek2(5) for details.

mustek

Supports most Mustek SCSI flatbed scanners including the Paragon and ScanExpress series and the 600 II N and 600 II EP (non-SCSI). Some Trust scanners are also supported. See sane-mustek(5) for details.

mustek_pp

Supports Mustek parallel port flatbed scanners. See sane-mustek_pp(5) for details.

mustek_usb

Supports some Mustek ScanExpress USB flatbed scanners. See sane-mustek_usb(5) for details.

mustek_usb2

Supports scanners using the SQ113 chipset like the Mustek BearPaw 2448 TA Pro USB flatbed scanner. See sane-mustek_usb2(5) for details.

nec

Supports the NEC PC-IN500/4C SCSI scanner. See sane-nec(5) for details.

niash

Supports the Agfa Snapscan Touch and the HP ScanJet 3300c, 3400c, and 4300c USB flatbed scanners. See sane-niash(5) for details.

p5

Supports the Primax PagePartner. See sane-p5(5) for details.

pie

Supports Pacific Image Electronics (PIE) and Devcom SCSI flatbed scanners. See sane-pie(5) for details.

pixma

Supports Canon PIXMA MP series (multi-function devices), Canon imageCLASS series (laser devices), Canon MAXIFY series and some Canon CanoScan series. See sane-pixma(5) for details.

plustek

Supports USB flatbed scanners that use the National Semiconductor LM983[1/2/3] chipset aka Merlin. Scanners using this LM983x chips include some models from Plustek, KYE/Genius, Hewlett-Packard, Mustek, Umax, Epson, and Canon. See sane-plustek(5) for details.

plustek_pp

Supports Plustek parallel port flatbed scanners using the Plustek ASIC P96001, P96003, P98001 and P98003, which includes some models from Plustek, KYE/Genius, Primax. See sane-plustek_pp(5) for details.

ricoh

Supports the Ricoh flatbed scanners IS50 and IS60. See sane-ricoh(5) for details.

ricoh2

Supports the Ricoh flatbed scanners: SG-3100SNw, SP-100SU, and SP-111SU. See sane-ricoh2(5) for details.

s9036

Supports Siemens 9036 flatbed scanners. See sane-s9036(5) for details.

sceptre

Supports the Sceptre S1200 flatbed scanner. See sane-sceptre(5) for details.

sharp

Supports Sharp SCSI scanners. See sane-sharp(5) for details.

sm3600

Supports the Microtek ScanMaker 3600 USB scanner. See sane-sm3600(5) for details.

sm3840

Supports the Microtek ScanMaker 3840 USB scanner. See sane-sm3840(5) for details.

snapscan

Supports AGFA SnapScan flatbed scanners including some which are rebadged to other brands. See sane-snapscan(5) for details.

sp15c

Supports the Fujitsu FCPA ScanPartner 15C flatbed scanner. See sane-sp15c(5) for details.

st400

Supports the Siemens ST400 and ST800. See sane-st400(5) for details.

tamarack

Supports Tamarack Artiscan flatbed scanners. See sane-tamarack(5) for details.

teco1 teco2 teco3

Supports some TECO scanners, usually sold under the Relisys, Trust, Primax, Piotech, Dextra names. See sane-teco1(5), sane-teco2(5) and sane-teco3(5) for details.

u12

Supports USB flatbed scanners based on Plustek's ASIC 98003 (parallel-port ASIC) and a GeneSys Logics' USB-parport bridge chip like the Plustek OpticPro U(T)12. See sane-u12(5) for details.

umax

Supports UMAX-SCSI-scanners and some Linotype Hell SCSI-scanners. See sane-umax(5) for details.

umax_pp

Supports Umax parallel port flatbed scanners and the HP 3200C. See sane-umax_pp(5) for details.

umax1200u

Supports the UMAX Astra 1220U (USB) flatbed scanner (and also the UMAX Astra 2000U, sort of). See sane-umax1220u(5) for details.

xerox_mfp

Supports multiple Samsung-based Samsung, Xerox, and Dell scanners. See sane-xerox_mfp(5) for details.

Also, have a look at the backend information page at http://www.sane-project.org/sane-supported-devices.html and the list of projects in /usr/share/doc/sane-backends/PROJECTS.

## BACKENDS FOR DIGITAL CAMERAS
dc210

Supports the Kodak DC210 Digital Camera. See sane-dc210(5).

dc240

Supports the Kodak DC240 Digital Camera. See dc240(5).

dc25

Supports Kodak DC20/DC25 Digital Cameras. See dc25(5).

dmc

Supports the Polaroid Digital Microscope Camera. See dmc(5).

gphoto2

Supports digital cameras supported by the gphoto2 library package. (See http://www.gphoto.org for more information and a list of supported cameras.) Gphoto2 supports over 140 different camera models. However, please note that more development and testing is needed before all of these cameras will be supported by SANE backend. See gphoto2(5).

qcam

Supports Connectix QuickCam cameras. See qcam(5).

stv680

Supports webcams with a stv680 chip. See stv680(5) for details.

Also, have a look at the backend information page at http://www.sane-project.org/sane-supported-devices.html and the list of projects in /usr/share/doc/sane-backends/PROJECTS.

## MISCELLANEOUS BACKENDS
dll

Implements a SANE backend that provides access to an arbitrary number of other SANE backends by dynamic loading. See sane-dll(5).

net

The SANE network daemon saned(8) provides access to scanners located on different computers in connection with the sane-net(5) backend. See saned(8).

pnm

PNM image reader pseudo-backend. The purpose of this backend is primarily to aid in debugging of SANE frontends. See sane-pnm(5).

pint

Supports scanners that use the PINT (Pint Is Not Twain) device driver. The PINT driver is being actively developed on the OpenBSD platform, and has been ported to a few other *NIX-like operating systems. See sane-pint(5).

test

Tests frontends and the SANE installation. It provides test pictures and various test options. See sane-test(5).

v4l

Provides generic access to video cameras and similar equipment using the V4L (Video for Linux) API. See sane-v4l(5).

Also, have a look at the backend information page at http://www.sane-project.org/sane-supported-devices.html and the list of projects in /usr/share/doc/sane-backends/PROJECTS.

## CHANGING THE TOP-LEVEL BACKEND
By default, all SANE backends (drivers) are loaded dynamically by the sane-dll meta backend. If you have any questions about the dynamic loading, read sane-dll(5). SANE frontends can also be linked to other backends directly by copying or linking a backend to libsane.so in /usr/lib64/sane.

## DEVELOPER'S DOCUMENTATION
It's not hard to write a SANE backend. It can take some time, however. You should have basic knowledge of C and enough patience to work through the documentation and find out how your scanner works. Appended is a list of some documents that help to write backends and frontends.

The SANE standard defines the application programming interface (API) that is used to communicate between frontends and backends. It can be found at http://sane-project.gitlab.io/standard/ .

There is some more information for programmers in /usr/share/doc/sane-backends/backend-writing.txt. Most of the internal SANE routines (sanei) are documented using doxygen: http://www.sane-project.org/sanei/. Before a new backend or frontend project is started, have a look at /usr/share/doc/sane-backends/PROJECTS for projects that are planned or not yet included into the SANE distribution and at our bug-tracking system: http://www.http://www.sane-project.org/bugs.html.

There are some links on how to find out about the protocol of a scanner: http://www.meier-geinitz.de/sane/misc/develop.html.

If you start writing a backend or frontend or any other part of SANE, please contact the sane-devel mailing list for coordination so that work is not duplicated.

## FILES
/etc/sane.d/*.conf

The backend configuration files.

/usr/lib64/sane/libsane-*.a

The static libraries implementing the backends.

/usr/lib64/sane/libsane-*.so

The shared libraries implementing the backends (present on systems that support dynamic loading).

/usr/share/doc/sane-backends/*

SANE documentation: The READMEs, text files for backends etc.

## PROBLEMS
If your device isn't found but you know that it is supported, make sure that it is detected by your operating system. For SCSI and USB scanners, use the sane-find-scanner(1) utility. It prints one line for each scanner it has detected and some comments (#). If sane-find-scanner(1) finds your scanner only as root but not as normal user, the permissions for the device files are not adjusted correctly. If the scanner isn't found at all, the operating system hasn't detected it and may need some help. Depending on the type of your scanner, read sane-usb(5) or sane-scsi(5). If your scanner (or other device) is not connected over the SCSI bus or USB, read the backend's manual page for details on how to set it up.

Is your scanner detected by the operating system but not by SANE? Try scanimage -L. If the scanner is not found, check that the backend's name is mentioned in /etc/sane.d/dll.conf. Some backends are commented out by default. Remove the comment sign for your backend in this case. Also some backends aren't compiled at all if one of their prerequisites are missing. Examples include dc210, dc240, canon_pp, hpsj5s, gphoto2, pint, qcam, v4l, net, sm3600, snapscan, pnm. If you need one of these backends and it isn't available, read the build instructions in the README file and the individual manual pages of the backends.

Another reason for not being detected by scanimage -L may be a missing or incorrect configuration in the backend's configuration file. While SANE tries to automatically find most scanners, some can't be setup correctly without the intervention of the administrator. Also on some operating systems auto-detection may not work. Check the backend's manual page for details.

If your scanner is still not found, try setting the various environment variables that are available to assist in debugging. The environment variables are documented in the relevant manual pages. For example, to get the maximum amount of debug information when testing a Mustek SCSI scanner, set environment variables SANE_DEBUG_DLL, SANE_DEBUG_MUSTEK, and SANE_DEBUG_SANEI_SCSI to 128 and then invoke scanimage -L. The SANE_DEBUG_DLL messages tell if the sane-mustek(5) backend was found and loaded at all. The SANE_DEBUG_MUSTEK messages explain what the backend is doing while the SANE_DEBUG_SCSI debugging shows the low level handling. If you can't find out what's going on by checking the messages carefully, contact the sane-devel mailing list for help (see REPORTING BUGS below).

Now that your scanner is found by scanimage -L, try to do a scan: scanimage >image.pnm. This command starts a scan for the default scanner with default settings. All the available options are listed by running scanimage --help. If scanning aborts with an error message, turn on debugging as mentioned above. Maybe the configuration file needs some tuning, e.g. to setup the path to a firmware that is needed by some scanners. See the backend's manual page for details. If you can't find out what's wrong, contact sane-devel.

To check that the SANE libraries are installed correctly you can use the test backend, even if you don't have a scanner or other SANE device:

scanimage -d test -T

You should get a list of PASSed tests. You can do the same with your backend by changing "test" to your backend's name.

So now scanning with scanimage (1) works and you want to use one of the graphical frontends like xsane(1), xscanimage(1), or quiteinsane (1) but those frontends don't detect your scanner? One reason may be that you installed two versions of SANE. E.g. the version that was installed by your distribution in /usr and one you installed from source in /usr/local/. Make sure that only one version is installed. Another possible reason is, that your system's dynamic loader can't find the SANE libraries. For Linux, make sure that /etc/ld.so.conf contains /usr/local/lib and does not contain /usr/local/lib/sane. See also the documentation of the frontends.

## HOW CAN YOU HELP SANE
We appreciate any help we can get. Please have a look at our web page about contributing to SANE: http://www.sane-project.org/contrib.html

## CONTACT
For reporting bugs or requesting new features, please use our bug-tracking system: http://www.sane-project.org/bugs.html. You can also contact the author of your backend directly. Usually the email address can be found in the /usr/share/doc/sane-backends/AUTHORS file or the backend's manpage. For general discussion about SANE, please use the SANE mailing list sane-devel (see http://www.sane-project.org/mailing-lists.html for details).

## SEE ALSO
saned(8), sane-find-scanner(1), scanimage(1), sane-abaton(5), sane-agfafocus(5), sane-apple(5), sane-artec(5), sane-artec_eplus48u(5), sane-as6e(5), sane-avision(5), sane-bh(5), sane-canon(5), sane-canon630u(5), sane-canon_dr(5), sane-canon_pp(5), sane-cardscan(5), sane-coolscan(5), sane-coolscan2(5), sane-coolscan3(5), sane-dc210(5), sane-dc240(5), sane-dc25(5), sane-dll(5), sane-dmc(5), sane-epson(5), sane-epson2(5), sane-escl(5), sane-fujitsu(5), sane-genesys(5), sane-gphoto2(5), sane-gt68xx(5), sane-hp(5), sane-hpsj5s(5), sane-hp3500(5), sane-hp3900(5), sane-hp4200(5), sane-hp5400(5), sane-hpljm1005(5), sane-ibm(5), sane-kodak(5), sane-leo(5), sane-lexmark(5), sane-ma1509(5), sane-matsushita(5), sane-microtek2(5), sane-microtek(5), sane-mustek(5), sane-mustek_pp(5), sane-mustek_usb(5), sane-mustek_usb2(5), sane-nec(5), sane-net(5), sane-niash(5), sane-pie(5), sane-pint(5), sane-plustek(5), sane-plustek_pp(5), sane-pnm(5), sane-qcam(5), sane-ricoh(5), sane-ricoh2(5), sane-s9036(5), sane-sceptre(5), sane-scsi(5), sane-sharp(5), sane-sm3600(5), sane-sm3840(5), sane-snapscan(5), sane-sp15c(5), sane-st400(5), sane-stv680(5), sane-tamarack(5), sane-teco1(5), sane-teco2(5), sane-teco3(5), sane-test(5), sane-u12(5), sane-umax1220u(5), sane-umax(5), sane-umax_pp(5), sane-usb(5), sane-v4l(5), sane-xerox_mfp(5)

## AUTHOR
David Mosberger-Tang and many many more (see /usr/share/doc/sane-backends/AUTHORS for details). This man page was written by Henning Meier-Geinitz. Quite a lot of text was taken from the SANE standard, several man pages, and README files.


schroot-faq

package: schroot

title: schroot-faq(7)

summary: frequently asked questions

text:
# schroot-faq(7)

## NAME
schroot - frequently asked questions

## DESCRIPTION
This manual page covers various frequently asked questions about configuration and usage of schroot.

## CONFIGURATION

### Why is schroot overwriting configuration files in the chroot?
By default, schroot copies over the system NSS databases (‘passwd’, ‘shadow’, ‘group’, ‘gshadow’, ‘services’, ‘protocols’, ‘networks’, and ‘hosts’, etc.) into the chroot. The reason for this is that the chroot environment is not a completely separate system, and it copying them over keeps them synchronised. However, this is not always desirable, particularly if installing a package in the chroot creates system users and groups which are not present on the host, since these will disappear next time the databases are copied over.

The suggested workaround here is to disable the copying. This may be achieved by setting the setup.nssdatabases key to be empty in schroot.conf. In prior schroot releases, this was done by commenting out the NSSDATABASES file for the chroot (/etc/schroot/default/config by default). The database list may also be customised by editing the file containing the database list (/etc/schroot/default/nssdatabases by default).

In the future, we will be working on a better scheme for keeping the host and chroot databases in sync which can merge entries rather than overwriting the entire database, which would preserve chroot-specific changes.

### Should I use the plain or directory chroot type?
These two chroot types are basically equivalent, since they are both just directories in the filesystem. plain is very simple and does not perform any setup tasks; the only reason you would want to use it is if you're upgrading from a program such as dchroot(1) or chroot(8) which don't do anything other than running a command or shell in a directory. On the other hand, directory chroots do run setup scripts, which can mount additional filesystems and do other setup tasks.

## ADVANCED CONFIGURATION

### What are snapshots and unions?
Some chroot types support cloning. This means when you start a session, you get a copy of the chroot which lasts just for the lifetime of the session. This is useful when you want a temporary clean copy of a system for a single task, which is then automatically deleted when you're done with it. For example, the Debian package build dæmons run sbuild(1) to build Debian packages, and this program uses schroot to create a clean build environment for each package. Without snapshotting, the chroot would need to be reset to its initial state at the end of each build to make it ready for the next one, and any debris left over from package removals or earlier builds could interfere with the next build.

The most commonly-used snapshotting method is to use LVM snapshots (chroot type ‘lvm-snapshot’). In this case the chroot must exist on an LVM logical volume (LV); snapshots of an LV may then be made with lvcreate(8) during chroot session setup. However, these use up a lot of disk space. A newer method is to use Btrfs snapshots which use up much less disk space (chroot type ‘btrfs-snapshot’), and may be more reliable than LVM snapshots. Btrfs is however still experimental, but it is hoped that it will become the recommended method as it matures.

Unions are an alternative to snapshots. In this situation, instead of creating a copy of the chroot filesystem, we overlay a read-write temporary filesystem on top of the chroot filesystem so that any modifications are stored in the overlay, leaving the original chroot filesystem untouched. The Linux kernel has yet to integrate support for union filesystems such as aufs and unionfs, so LVM snapshots are still the recommended method at present.

## USAGE

### Can I run a dæmons in a chroot?
A common problem is trying to run a dæmon in a chroot, and finding that this doesn't work. Typically, the dæmon is killed shortly after it starts up.

When schroot runs, it begins a session, runs the specified command or shell, waits for the command or shell to exit, and then it ends the session. For a normal command or shell, this works just fine. However, dæmons normally start up by running in the background and detaching from the controlling terminal. They do this by forking twice and letting the parent processes exit. Unfortunately, this means schroot detects that the program exited (the dæmon is a orphaned grandchild of this process) and it then ends the session. Part of ending the session is killing all processes running inside the chroot, which means the dæmon is killed as the session ends.

In consequence, it's not possible to run a dæmon directly with schroot. You can however do it if you create a session with --begin-session and then run the dæmon with --run-session. It's your responsibility to end the session with --end-session when the daemon has terminated or you no longer need it.

### How do I manually cleaning up a broken session?
Occasionally, it may be necessary to manually clean up sessions. If something changes on your system which causes the setup scripts to fail when ending a session, for example removal of a needed file or directory, it may not be possible for schroot to clean everything up automatically. For each of the session directories listed in the “Session directories” section in schroot(1), any files with the name of the session ID need deleting, and any directories with the name of the session ID need umounting (if there are any filesystems mounted under it), and then also removing.

For example, to remove a session named my-session by hand:

•

Remove the session configuration file

```
% rm /var/lib/schroot/session/my-session↵

```

•

Check for mounted filesystems

```
% /usr/libexec/schroot/schroot-listmounts -m \

  /var/run/schroot/mount/my-session↵

```

•

Unmount any mounted filesystems

•

Remove /var/run/schroot/mount/my-session

•

Repeat for the other directories such as /var/lib/schroot/union/underlay, /var/lib/schroot/union/overlay and /var/lib/schroot/unpack

NOTE: Do not remove any directories without checking if there are any filesystems mounted below them, since filesystems such as /home could still be bind mounted. Doing so could cause irretrievable data loss!

## ADVANCED USAGE

### How do I use sessions?
In normal use, running a command might look like this:

```
% schroot -c squeeze -- command↵
```

which would run the command command in the squeeze chroot. While it's not apparent that a session is being used here, schroot is actually doing the following steps:

•

Creating a session using the squeeze chroot. This will be automatically given a unique name, such as squeeze-57a69547-e014-4f5d-a98b-f4f35a005307, though you don't usually need to know about this

•

Setup scripts are run to create the session chroot and configure it for you

•

The command command is run inside the session chroot

•

Setup scripts are run to clean up the session chroot

•

The session is deleted

Now, if you wanted to run more than one command, you could run a shell and run them interactively, or you could put them into shell script and run that instead. But you might want to do something in between, such as running arbitrary commands from a program or script where you don't know which commands to run in advance. You might also want to preseve the chroot state in between commands, where the normal automatic session creation would reset the state in between each command. This is what sessions are for: once created, the session is persistent and won't be automatically removed. With a session, you can run as many commands as you like, but you need to create and delete the session by hand since schroot can't know by itself when you're done with it unlike in the single command case above. This is quite easy:

```
% schroot --begin-session -c squeeze↵
squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
```

This created a new session based upon the squeeze chroot. The unique name for the session, the session ID, was printed to standard output, so we could also save it as a shell variable at the same time like so:

```
% SESSION=$(schroot --begin-session -c squeeze)↵
% echo $SESSION↵
squeeze-57a69547-e014-4f5d-a98b-f4f35a005307
```

Now we have created the session and got the session ID, we can run commands in it using the session ID:

```
% schroot --run-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307 \

  -- command1↵
```

or

```
% schroot --run-session -c "$SESSION" -- command1↵
```

and then as many more commands as we like

```
% schroot --run-session -c "$SESSION" -- command2↵
% schroot --run-session -c "$SESSION" -- command3↵
% schroot --run-session -c "$SESSION" -- command4↵
```

etc.

When we are done with the session, we can remove it with --end-session:

```
% schroot --end-session -c squeeze-57a69547-e014-4f5d-a98b-f4f35a005307↵
```

or

```
% schroot --end-session -c "$SESSION"↵
```

Since the automatically generated session names can be long and unwieldy, the --session-name option allows you to provide you own name:

```
% schroot --begin-session -c squeeze --session-name my-name↵
my-name
```

## CONTRIBUTING

### Getting help and getting involved
The mailing list <buildd-tools-devel@lists.alioth.debian.org> is used for both user support and development discussion. The list may be subscribed to from the project website at https://alioth.debian.org/projects/buildd-tools/ or the Mailman list interface at http://lists.alioth.debian.org/mailman/listinfo/buildd-tools-devel.

### Reporting bugs
On Debian systems, bugs may be reported using the reportbug(1) tool, or alternatively by mailing <submit@bugs.debian.org> (see http://bugs.debian.org for details on how to do that).

### Getting the latest sources
schroot is maintained in the git version control system. You can get the latest sources from git://git.debian.org/git/buildd-tools/schroot.

```
% git clone git://git.debian.org/git/buildd-tools/schroot↵
```

The master branch containes the current development release. Stable releases are found on branches, for example the 1.4 series of releases are on the schroot-1.4 branch.

## AUTHORS
Roger Leigh.

## COPYRIGHT
Copyright © 2005-2012 Roger Leigh <rleigh@debian.org>

schroot 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 3 of the License, or (at your option) any later version.

## SEE ALSO
dchroot(1), schroot(1), sbuild(1), schroot-setup(5), schroot.conf(5).


layingsiege

package: siege

title: layingsiege(7)

summary: An HTTP/HTTPS stress tester

text:
# layingsiege(7)

## NAME
Siege - An HTTP/HTTPS stress tester was designed orignally as a internet usage simulator. In short, its role was to simulate the activity of many simultaneous users hitting a HTTP server. We were debugging some java code and during that process we arrived at a point where the code could withstand an acceptable number of users hitting a single URL but it could not withstand the seemingly random activity that characterizes many users hitting many URLs on a webserver.

In order to debug the problem in a lab environment, I developed a program that simply read a bunch of URLs ( we used images, scripts, static html, jsps, etc. ) into memory and hit them randomly. The result was a success. We were able to break the code in the lab, an occurance which ultimately allowed us to fix it and put it into production. As the developers code improved, siege improved until we ultimately had good java code and a pretty decent regression tool. It was helpful for us, I hope it is helpful to you.

In order to feel comfortable putting code into production, you need a way to measure its performance and to determine its threshold for failure. If you break your database pool at 250 simultaneous users and you average less then one-hundred simultaneous users and the code performs favorably, you can feel good about putting it into production. At the same time, if you should monitor trends in your site's activity and prepare for the moment when your traffic starts to near your threshold for failure.

As a webdeveloper or websystems administrator you have little to no control over your user group. They can visit your site anytime day or night. Your domain name could resemble a popular site, yoohoo.com? And when was the last time marketing informed you about an approaching advertising blitz? You must be prepared for anything. That is why stress and performance testing is so important. I would not recommend putting anything into production until you have a good feel for how it will perform under duress.

## LAYING SIEGE
Whenever we add new code to a webserver, we place the server "under siege." First we stressthe new URL(s) and then we pound the server with regression testing with the new URLs added to the configuration file. We want to see if the new code will stand on its own, plus we want to see if it will break anything else.

The following statistics were gleaned when I laid siege to a single URL on a http server:

Transactions: 1000 hits

Elapsed time: 617.99 secs

Data transferred: 4848000 bytes

Response time: 59.41 secs

Transaction rate: 1.62 trans/sec

Throughput: 7844.79 bytes/sec

Concurrency: 96.14

Status code 200: 1000

In the above example, we simulated 100 users hitting the same URL 10 times, a total of 1000 transactions. The elapsed time is measured from the first transaction to the last, in this case it took 617.99 seconds to hit the http server 1000 times. During that run, siege recieved a total of 4848000 bytes including headers. The response time is measured by the duration of each transaction divided by the number of transactions. The transaction rate is number of transactions divided by elapsed time. Throughput is the measure of bytes recieved divided by elapsed time. And the concurrency is the time of each transaction divided by the elapsed time. The final statistic is Status code 200. This is the number of pages that were effectively delivered without server errors.

To create this example, I ran siege on my Sun workstation and I pounded a GNU/Linux Intel box, essentially a workstation. The performance leaves a lot to be desired. One indication that the server is struggling is the high concurrency. The longer the transaction, the higher the concurrency. This server is taking a while to complete the transaction and it continues to open new sockets to handle all the additional requests. In truth the Linux box is suffering from a lack of RAM, it has about 200MB, hardly enough to be handling one hundred concurrent users. :-)

Now that we've stressed the URL(s) singly, we can add them to our main configuration file and stress them with the rest of the site. The default URLs file is SIEGE_HOME/etc/urls.txt.

Siege can allow websystems administrators a chance to see how their servers perform under duress. I recommend running server performance monitoring tools while it is under siege to gage your hardware / software configurations. The results can be surprising...

Siege was originally based on Lincoln Stein's torture.pl and if you cannot it on your architecture, it is recommended that you run that excellent perl script instead. I intentionally modeled my statistics output after his in order to maintain similar reference.

## COPYRIGHT
Copyright © 2000 2001 2004 Jeffrey Fulmer, et al. <jeff@joedog.org>

This program 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 Fo undation; either version 2 of the License, or (at your option) any later version.

This program 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., 675 Mass Ave, Cambridge, MA 02139, USA.

## AVAILABILITY
The most recent released version of siege is available by anonymous FTP from sid.joedog.org in the directory pub/siege.

## SEE ALSO
siege(1) siege.config(1) urls_txt(5)


soxformat

package: sox-base

title: soxformat(7)

text:
# soxformat(7)

## NAME
SoX - Sound eXchange, the Swiss Army knife of audio manipulation

## DESCRIPTION
This manual describes SoX supported file formats and audio device types; the SoX manual set starts with sox(1).

Format types that can SoX can determine by a filename extension are listed with their names preceded by a dot. Format types that are optionally built into SoX are marked `(optional)'.

Format types that can be handled by an external library via an optional pseudo file type (currently sndfile) are marked e.g. `(also with -t sndfile)'. This might be useful if you have a file that doesn't work with SoX's default format readers and writers, and there's an external reader or writer for that format.

To see if SoX has support for an optional format or device, enter sox -h and look for its name under the list: `AUDIO FILE FORMATS' or `AUDIO DEVICE DRIVERS'.

### SOX FORMATS & DEVICE DRIVERS
.raw (also with -t sndfile), .f32, .f64, .s8, .s16, .s24, .s32,

.u8, .u16, .u24, .u32, .ul, .al, .lu, .la

Raw (headerless) audio files. For raw, the sample rate and the data encoding must be given using command-line format options; for the other listed types, the sample rate defaults to 8kHz (but may be overridden), and the data encoding is defined by the given suffix. Thus f32 and f64 indicate files encoded as 32 and 64-bit (IEEE single and double precision) floating point PCM respectively; s8, s16, s24, and s32 indicate 8, 16, 24, and 32-bit signed integer PCM respectively; u8, u16, u24, and u32 indicate 8, 16, 24, and 32-bit unsigned integer PCM respectively; ul indicates `μ-law' (8-bit), al indicates `A-law' (8-bit), and lu and la are inverse bit order `μ-law' and inverse bit order `A-law' respectively. For all raw formats, the number of channels defaults to 1 (but may be overridden). Headerless audio files on a SPARC computer are likely to be of format ul; on a Mac, they're likely to be u8 but with a sample rate of 11025 or 22050 Hz.

See .ima and .vox for raw ADPCM formats, and .cdda for raw CD digital audio.

.f4, .f8, .s1, .s2, .s3, .s4,

.u1, .u2, .u3, .u4, .sb, .sw, .sl, .ub, .uw

Deprecated aliases for f32, f64, s8, s16, s24, s32,

u8, u16, u24, u32, s8, s16, s32, u8, and u16 respectively.

.8svx (also with -t sndfile)

Amiga 8SVX musical instrument description format.

.aiff, .aif (also with -t sndfile)

AIFF files as used on old Apple Macs, Apple IIc/IIgs and SGI. SoX's AIFF support does not include multiple audio chunks, or the 8SVX musical instrument description format. AIFF files are multimedia archives and can have multiple audio and picture chunks - you may need a separate archiver to work with them. With Mac OS X, AIFF has been superseded by CAF.

.aiffc, .aifc (also with -t sndfile)

AIFF-C is a format based on AIFF that was created to allow handling compressed audio. It can also handle little endian uncompressed linear data that is often referred to as sowt encoding. This encoding has also become the defacto format produced by modern Macs as well as iTunes on any platform. AIFF-C files produced by other applications typically have the file extension .aif and require looking at its header to detect the true format. The sowt encoding is the only encoding that SoX can handle with this format. AIFF-C is defined in DAVIC 1.4 Part 9 Annex B. This format is referred from ARIB STD-B24, which is specified for Japanese data broadcasting. Any private chunks are not supported.

alsa (optional)

Advanced Linux Sound Architecture device driver; supports both playing and recording audio. ALSA is only used in Linux-based operating systems, though these often support OSS (see below) as well. Examples:

```
	sox infile -t alsa
	sox infile -t alsa default
	sox infile -t alsa plughw:0,0
	sox -b 16 -t alsa hw:1 outfile

```

See also play(1), rec(1), and sox(1) -d.

.amb

Ambisonic B-Format: a specialisation of .wav with between 3 and 16 channels of audio for use with an Ambisonic decoder. See http://www.ambisonia.com/Members/mleese/file-format-for-b-format for details. It is up to the user to get the channels together in the right order and at the correct amplitude.

.amr-nb (optional)

Adaptive Multi Rate - Narrow Band speech codec; a lossy format used in 3rd generation mobile telephony and defined in 3GPP TS 26.071 et al. AMR-NB audio has a fixed sampling rate of 8 kHz and supports encoding to the following bit-rates (as selected by the -C option): 0 = 4.75 kbit/s, 1 = 5.15 kbit/s, 2 = 5.9 kbit/s, 3 = 6.7 kbit/s, 4 = 7.4 kbit/s 5 = 7.95 kbit/s, 6 = 10.2 kbit/s, 7 = 12.2 kbit/s.

.amr-wb (optional)

Adaptive Multi Rate - Wide Band speech codec; a lossy format used in 3rd generation mobile telephony and defined in 3GPP TS 26.171 et al. AMR-WB audio has a fixed sampling rate of 16 kHz and supports encoding to the following bit-rates (as selected by the -C option): 0 = 6.6 kbit/s, 1 = 8.85 kbit/s, 2 = 12.65 kbit/s, 3 = 14.25 kbit/s, 4 = 15.85 kbit/s 5 = 18.25 kbit/s, 6 = 19.85 kbit/s, 7 = 23.05 kbit/s, 8 = 23.85 kbit/s.

ao (optional)

Xiph.org's Audio Output device driver; works only for playing audio. It supports a wide range of devices and sound systems - see its documentation for the full range. For the most part, SoX's use of libao cannot be configured directly; instead, libao configuration files must be used. The filename specified is used to determine which libao plugin to use. Normally, you should specify `default' as the filename. If that doesn't give the desired behavior then you can specify the short name for a given plugin (such as pulse for pulse audio plugin). Examples:

```
	sox infile -t ao
	sox infile -t ao default
	sox infile -t ao pulse

```

See also play(1) and sox(1) -d.

.au, .snd (also with -t sndfile)

Sun Microsystems AU files. There are many types of AU file; DEC has invented its own with a different magic number and byte order. To write a DEC file, use the -L option with the output file options. Some .au files are known to have invalid AU headers; these are probably original Sun μ-law 8000 Hz files and can be dealt with using the .ul format (see below).

It is possible to override AU file header information with the -r and -c options, in which case SoX will issue a warning to that effect.

.avr

Audio Visual Research format; used by a number of commercial packages on the Mac.

.caf (optional)

Apple's Core Audio File format.

.cdda, .cdr

`Red Book' Compact Disc Digital Audio (raw audio). CDDA has two audio channels formatted as 16-bit signed integers (big endian)at a sample rate of 44.1 kHz. The number of (stereo) samples in each CDDA track is always a multiple of 588.

coreaudio (optional)

Mac OSX CoreAudio device driver: supports both playing and recording audio. If a filename is not specific or if the name is "default" then the default audio device is selected. Any other name will be used to select a specific device. The valid names can be seen in the System Preferences->Sound menu and then under the Output and Input tabs. Examples:

```
	sox infile -t coreaudio
	sox infile -t coreaudio default
	sox infile -t coreaudio "Internal Speakers"

```

See also play(1), rec(1), and sox(1) -d.

.cvsd, .cvs

Continuously Variable Slope Delta modulation. A headerless format used to compress speech audio for applications such as voice mail. This format is sometimes used with bit-reversed samples - the -X format option can be used to set the bit-order.

.cvu

Continuously Variable Slope Delta modulation (unfiltered). This is an alternative handler for CVSD that is unfiltered but can be used with any bit-rate. E.g.

```
	sox infile outfile.cvu rate 28k
	play -r 28k outfile.cvu sinc -3.4k

```

.dat

Text Data files. These files contain a textual representation of the sample data. There is one line at the beginning that contains the sample rate, and one line that contains the number of channels. Subsequent lines contain two or more numeric data intems: the time since the beginning of the first sample and the sample value for each channel. Values are normalized so that the maximum and minimum are 1 and -1. This file format can be used to create data files for external programs such as FFT analysers or graph routines. SoX can also convert a file in this format back into one of the other file formats.

Example containing only 2 stereo samples of silence:

```
    ; Sample Rate 8012

    ; Channels 2

                0	0	0

    0.00012481278	0	0

```

.dvms, .vms

Used in Germany to compress speech audio for voice mail. A self-describing variant of cvsd.

.fap (optional)

See .paf.

.flac (optional; also with -t sndfile)

Xiph.org's Free Lossless Audio CODEC compressed audio. FLAC is an open, patent-free CODEC designed for compressing music. It is similar to MP3 and Ogg Vorbis, but lossless, meaning that audio is compressed in FLAC without any loss in quality. SoX can read native FLAC files (.flac) but not Ogg FLAC files (.ogg). [But see .ogg below for information relating to support for Ogg Vorbis files.]

SoX can write native FLAC files according to a given or default compression level. 8 is the default compression level and gives the best (but slowest) compression; 0 gives the least (but fastest) compression. The compression level is selected using the -C option [see sox(1)] with a whole number from 0 to 8.

.fssd

An alias for the .u8 format.

.gsrt

Grandstream ring-tone files. Whilst this file format can contain A-Law, μ-law, GSM, G.722, G.723, G.726, G.728, or iLBC encoded audio, SoX supports reading and writing only A-Law and μ-law. E.g.

```
   sox music.wav -t gsrt ring.bin

   play ring.bin

```

.gsm (optional; also with -t sndfile)

GSM 06.10 Lossy Speech Compression. A lossy format for compressing speech which is used in the Global Standard for Mobile telecommunications (GSM). It's good for its purpose, shrinking audio data size, but it will introduce lots of noise when a given audio signal is encoded and decoded multiple times. This format is used by some voice mail applications. It is rather CPU intensive.

.hcom

Macintosh HCOM files. These are Mac FSSD files with Huffman compression.

.htk

Single channel 16-bit PCM format used by HTK, a toolkit for building Hidden Markov Model speech processing tools.

.ircam (also with -t sndfile)

Another name for .sf.

.ima (also with -t sndfile)

A headerless file of IMA ADPCM audio data. IMA ADPCM claims 16-bit precision packed into only 4 bits, but in fact sounds no better than .vox.

.lpc, .lpc10

LPC-10 is a compression scheme for speech developed in the United States. See http://www.arl.wustl.edu/~jaf/lpc/ for details. There is no associated file format, so SoX's implementation is headerless.

.mat, .mat4, .mat5 (optional)

Matlab 4.2/5.0 (respectively GNU Octave 2.0/2.1) format (.mat is the same as .mat4).

.m3u

A playlist format; contains a list of audio files. SoX can read, but not write this file format. See [1] for details of this format.

.maud

An IFF-conforming audio file type, registered by MS MacroSystem Computer GmbH, published along with the `Toccata' sound-card on the Amiga. Allows 8bit linear, 16bit linear, A-Law, μ-law in mono and stereo.

.mp3, .mp2 (optional read, optional write)

MP3 compressed audio; MP3 (MPEG Layer 3) is a part of the patent-encumbered MPEG standards for audio and video compression. It is a lossy compression format that achieves good compression rates with little quality loss. Because MP3 is patented, SoX cannot be distributed with MP3 support without incurring the patent holder's fees. Users who require SoX with MP3 support must currently compile and build SoX with the MP3 libraries (LAME & MAD) from source code, or, in some cases, obtain pre-built dynamically loadable libraries.

When reading MP3 files, up to 28 bits of precision is stored although only 16 bits is reported to user. This is to allow default behavior of writing 16 bit output files. A user can specify a higher precision for the output file to prevent lossing this extra information. MP3 output files will use up to 24 bits of precision while encoding.

MP3 compression parameters can be selected using SoX's -C option as follows (note that the current syntax is subject to change):

The primary parameter to the LAME encoder is the bit rate. If the value of the -C value is a positive integer, it's taken as the bitrate in kbps (e.g. if you specify 128, it uses 128 kbps).

The second most important parameter is probably "quality" (really performance), which allows balancing encoding speed vs. quality. In LAME, 0 specifies highest quality but is very slow, while 9 selects poor quality, but is fast. (5 is the default and 2 is recommended as a good trade-off for high quality encodes.)

Because the -C value is a float, the fractional part is used to select quality. 128.2 selects 128 kbps encoding with a quality of 2. There is one problem with this approach. We need 128 to specify 128 kbps encoding with default quality, so 0 means use default. Instead of 0 you have to use .01 (or .99) to specify the highest quality (128.01 or 128.99).

LAME uses bitrate to specify a constant bitrate, but higher quality can be achieved using Variable Bit Rate (VBR). VBR quality (really size) is selected using a number from 0 to 9. Use a value of 0 for high quality, larger files, and 9 for smaller files of lower quality. 4 is the default.

In order to squeeze the selection of VBR into the the -C value float we use negative numbers to select VRR. -4.2 would select default VBR encoding (size) with high quality (speed). One special case is 0, which is a valid VBR encoding parameter but not a valid bitrate. Compression value of 0 is always treated as a high quality vbr, as a result both -0.2 and 0.2 are treated as highest quality VBR (size) and high quality (speed).

See also Ogg Vorbis for a similar format.

.nist (also with -t sndfile)

See .sph.

.ogg, .vorbis (optional)

Xiph.org's Ogg Vorbis compressed audio; an open, patent-free CODEC designed for music and streaming audio. It is a lossy compression format (similar to MP3, VQF & AAC) that achieves good compression rates with a minimum amount of quality loss. SoX can decode all types of Ogg Vorbis files, and can encode at different compression levels/qualities given as a number from -1 (highest compression/lowest quality) to 10 (lowest compression, highest quality). By default the encoding quality level is 3 (which gives an encoded rate of approx. 112kbps), but this can be changed using the -C option (see above) with a number from -1 to 10; fractional numbers (e.g. 3.6) are also allowed. Decoding is somewhat CPU intensive and encoding is very CPU intensive.

See also .mp3 for a similar format.

.opus (optional)

Xiph.org's Opus compressed audio; an open, lossy, low-latency codec offering a wide range of compression rates. It uses the Ogg container. SoX can only read Opus files, not write them.

oss (optional)

Open Sound System /dev/dsp device driver; supports both playing and recording audio. OSS support is available in Unix-like operating systems, sometimes together with alternative sound systems (such as ALSA). Examples:

```
	sox infile -t oss
	sox infile -t oss /dev/dsp
	sox -b 16 -t oss /dev/dsp outfile

```

See also play(1), rec(1), and sox(1) -d.

.paf, .fap (optional)

Ensoniq PARIS file format (big and little-endian respectively).

.pls

A playlist format; contains a list of audio files. SoX can read, but not write this file format. See [2] for details of this format. Note: SoX support for SHOUTcast PLS relies on wget(1) and is only partially supported: it's necessary to specify the audio type manually, e.g.

```
	play -t mp3 "http://a.server/pls?rn=265&file=filename.pls"

```

and SoX does not know about alternative servers - hit Ctrl-C twice in quick succession to quit.

.prc

Psion Record. Used in Psion EPOC PDAs (Series 5, Revo and similar) for System alarms and recordings made by the built-in Record application. When writing, SoX defaults to A-law, which is recommended; if you must use ADPCM, then use the -e ima-adpcm switch. The sound quality is poor because Psion Record seems to insist on frames of 800 samples or fewer, so that the ADPCM CODEC has to be reset at every 800 frames, which causes the sound to glitch every tenth of a second.

pulseaudio (optional)

PulseAudio driver; supports both playing and recording of audio. PulseAudio is a cross platform networked sound server. If a file name is specified with this driver, it is ignored. Examples:

```
	sox infile -t pulseaudio
	sox infile -t pulseaudio default

```

See also play(1), rec(1), and sox(1) -d.

.pvf (optional)

Portable Voice Format.

.sd2 (optional)

Sound Designer 2 format.

.sds (optional)

MIDI Sample Dump Standard.

.sf (also with -t sndfile)

IRCAM SDIF (Institut de Recherche et Coordination Acoustique/Musique Sound Description Interchange Format). Used by academic music software such as the CSound package, and the MixView sound sample editor.

.sln

Asterisk PBX `signed linear' 8khz, 16-bit signed integer, little-endian raw format.

.sph, .nist (also with -t sndfile)

SPHERE (SPeech HEader Resources) is a file format defined by NIST (National Institute of Standards and Technology) and is used with speech audio. SoX can read these files when they contain μ-law and PCM data. It will ignore any header information that says the data is compressed using shorten compression and will treat the data as either μ-law or PCM. This will allow SoX and the command line shorten program to be run together using pipes to encompasses the data and then pass the result to SoX for processing.

.smp

Turtle Beach SampleVision files. SMP files are for use with the PC-DOS package SampleVision by Turtle Beach Softworks. This package is for communication to several MIDI samplers. All sample rates are supported by the package, although not all are supported by the samplers themselves. Currently loop points are ignored.

.snd

See .au, .sndr and .sndt.

sndfile (optional)

This is a pseudo-type that forces libsndfile to be used. For writing files, the actual file type is then taken from the output file name; for reading them, it is deduced from the file.

sndio (optional)

OpenBSD audio device driver; supports both playing and recording audio.

```
	sox infile -t sndio

```

See also play(1), rec(1), and sox(1) -d.

.sndr

Sounder files. An MS-DOS/Windows format from the early '90s. Sounder files usually have the extension `.SND'.

.sndt

SoundTool files. An MS-DOS/Windows format from the early '90s. SoundTool files usually have the extension `.SND'.

.sou

An alias for the .u8 raw format.

.sox

SoX's native uncompressed PCM format, intended for storing (or piping) audio at intermediate processing points (i.e. between SoX invocations). It has much in common with the popular WAV, AIFF, and AU uncompressed PCM formats, but has the following specific characteristics: the PCM samples are always stored as 32 bit signed integers, the samples are stored (by default) as `native endian', and the number of samples in the file is recorded as a 64-bit integer. Comments are also supported. See `Special Filenames' in sox(1) for examples of using the .sox format with `pipes'.

sunau (optional)

Sun /dev/audio device driver; supports both playing and recording audio. For example:

```
	sox infile -t sunau /dev/audio

```

or

```
	sox infile -t sunau -e mu-law -c 1 /dev/audio

```

for older sun equipment. See also play(1), rec(1), and sox(1) -d.

.txw

Yamaha TX-16W sampler. A file format from a Yamaha sampling keyboard which wrote IBM-PC format 3.5" floppies. Handles reading of files which do not have the sample rate field set to one of the expected by looking at some other bytes in the attack/loop length fields, and defaulting to 33 kHz if the sample rate is still unknown.

.vms

See .dvms.

.voc (also with -t sndfile)

Sound Blaster VOC files. VOC files are multi-part and contain silence parts, looping, and different sample rates for different chunks. On input, the silence parts are filled out, loops are rejected, and sample data with a new sample rate is rejected. Silence with a different sample rate is generated appropriately. On output, silence is not detected, nor are impossible sample rates. SoX supports reading (but not writing) VOC files with multiple blocks, and files containing μ-law, A-law, and 2/3/4-bit ADPCM samples.

.vorbis

See .ogg.

.vox (also with -t sndfile)

A headerless file of Dialogic/OKI ADPCM audio data commonly comes with the extension .vox. This ADPCM data has 12-bit precision packed into only 4-bits. Note: some early Dialogic hardware does not always reset the ADPCM encoder at the start of each vox file. This can result in clipping and/or DC offset problems when it comes to decoding the audio. Whilst little can be done about the clipping, a DC offset can be removed by passing the decoded audio through a high-pass filter, e.g.:

```
	sox input.vox output.wav highpass 10

```

.w64 (optional)

Sonic Foundry's 64-bit RIFF/WAV format.

.wav (also with -t sndfile)

Microsoft .WAV RIFF files. This is the native audio file format of Windows, and widely used for uncompressed audio. Normally .wav files have all formatting information in their headers, and so do not need any format options specified for an input file. If any are, they will override the file header, and you will be warned to this effect. You had better know what you are doing! Output format options will cause a format conversion, and the .wav will written appropriately.

SoX can read and write linear PCM, floating point, μ-law, A-law, MS ADPCM, and IMA (or DVI) ADPCM encoded samples. WAV files can also contain audio encoded in many other ways (not currently supported with SoX) e.g. MP3; in some cases such a file can still be read by SoX by overriding the file type, e.g.

```
   play -t mp3 mp3-encoded.wav

```

Big endian versions of RIFF files, called RIFX, are also supported. To write a RIFX file, use the -B option with the output file options.

waveaudio (optional)

MS-Windows native audio device driver. Examples:

```
	sox infile -t waveaudio
	sox infile -t waveaudio default
	sox infile -t waveaudio 1
	sox infile -t waveaudio "High Definition Audio Device ("

```

If the device name is omitted, -1, or default, then you get the `Microsoft Wave Mapper' device. Wave Mapper means `use the system default audio devices'. You can control what `default' means via the OS Control Panel. If the device name given is some other number, you get that audio device by index; so recording with device name 0 would get the first input device (perhaps the microphone), 1 would get the second (perhaps line in), etc. Playback using 0 will get the first output device (usually the only audio device).

If the device name given is something other than a number, SoX tries to match it (maximum 31 characters) against the names of the available devices.

See also play(1), rec(1), and sox(1) -d.

.wavpcm

A non-standard, but widely used, variant of .wav. Some applications cannot read a standard WAV file header for PCM-encoded data with sample-size greater than 16-bits or with more than two channels, but can read a non-standard WAV header. It is likely that such applications will eventually be updated to support the standard header, but in the mean time, this SoX format can be used to create files with the non-standard header that should work with these applications. (Note that SoX will automatically detect and read WAV files with the non-standard header.) The most common use of this file-type is likely to be along the following lines:

```
	sox infile.any -t wavpcm -e signed-integer outfile.wav

```

.wv (optional)

WavPack lossless audio compression. Note that, when converting .wav to this format and back again, the RIFF header is not necessarily preserved losslessly (though the audio is).

.wve (also with -t sndfile)

Psion 8-bit A-law. Used on Psion SIBO PDAs (Series 3 and similar). This format is deprecated in SoX, but will continue to be used in libsndfile.

.xa

Maxis XA files. These are 16-bit ADPCM audio files used by Maxis games. Writing .xa files is currently not supported, although adding write support should not be very difficult.

.xi (optional)

Fasttracker 2 Extended Instrument format.

## SEE ALSO
sox(1), soxi(1), libsox(3), octave(1), wget(1)

The SoX web page at http://sox.sourceforge.net

SoX scripting examples at http://sox.sourceforge.net/Docs/Scripts

### References
[1]

Wikipedia, M3U, http://en.wikipedia.org/wiki/M3U

[2]

Wikipedia, PLS, http://en.wikipedia.org/wiki/PLS_(file_format)

## LICENSE
Copyright 1998-2013 Chris Bagwell and SoX Contributors.

Copyright 1991 Lance Norskog and Sundry Contributors.

## AUTHORS
Chris Bagwell (cbagwell@users.sourceforge.net). Other authors and contributors are listed in the ChangeLog file that is distributed with the source code.


make-srpm-cleanup

package: srpm-cleanup

title: make-srpm-cleanup(7)

text:
# make-srpm-cleanup(7)

## NAME
make-srpm-cleanup - truntate unused files in SRPM packages stage by stage

## SYNOPSIS
make status

make stage...

make stage...-status

make list-...

make show-...

make check-...

make update-...

make export...

make statclean

make clean...

make update-versions.sed

## DESCRIPTION
In order to control the process of SRPM cleanup with make(1) copy the example Makefile from /usr/share/doc/srpm-cleanup/Makefile.example to Makefile in the working directory and modify it in accordance with your needs. You can also write your own configuration Makefile from scratch but don´t forget to include /usr/share/srpm-cleanup/main.mk at its end.

### Stages
The whole process of SRPM cleanup is divided onto 5 following stages:

- Stage I: SRPM packages are rebuilt using hsh-separate-sources(1) and a list of unused files is written down for each package.

- Stage II: SRPM packages are rebuilt using srpm-cleanup(1) and a TAR with source files is written down for each package. Comparing to the original package, the resulting TAR doesn´t contain unused files.

- Stage III: For each TAR package the corresponding SRPM package is built using srpm-cleanup(1).

- Stage IV: SRPM packages from Stage III are rebuilt with hsh-separate-sources(1) in verification mode. The verification process checks there are no new unused files. However, in some situations that check should be toolerated (see TOOLERANCE below).

- Stage V: The resulting verified SRPM packages are rebuilt with additional options (for example --with-pre and --with-post). For packages that have failed with verification the corresponding original SRPMs are rebuilt instead.

On each stage the packages are rebuilt in parallel inside a number of hasher(1) slots on a set of build hosts. The results of that builds and the build log files are transferred from build hosts and collected in the configured directories. The results of one stage are used on the next stage.

When a package is processed the output of used tools such as hsh-separate-sources(1) is written to the stage log file. The tarnscript of low-level operation goes to the build log file. After the whole stage is passed the corresponding stage status file is updated. That status file is constituted from the stage log records plus a special status record for each package that is deduced from the stage log records related to it. With the stage status file it is very easy to find the resulting status of each particular package.

Knowing the resulting status of each package it is possible to retry the stage processing for only a subset of packages based on thier status and after making the necessary configuration changes (see "Stage retries" below).

For each stage the following common targets are available:

- stageN: Run the stage N for packages that havn´t yet been processed. Run the stage on all configured BUILDERS on all architectures (see CONFIGURATION below). The values for N are 1..4, 5v and 5o. The last two are for the separate substages of Stage V: rebuilt of verified and the original packages.

- stageN-status: Show statistics for stage N.

- list-stageN-C[-A]: List names and versions of packages that fall into category C and optionally architecture A in stage N. The packages are divided onto categories using information from the stage status file.

Available architectures A are those for which BUILDERS are defined (see CONFIGURATION below).

Popular C examples among different stages are:

- done: successfully built packages,

- noatt: there were no attempts to build these packages yet,

- excl: build failed because of ExclusiveArch or ExcludeArch declaration,

- blderr: any kind of build error,

- brkndep: build failed because of broken dependencies,

- chkerr: build failed in the %check section,

- nosrpm: the builder was unable to find the SRPM file for the given package,

- nospace: build failed due to no space left on device,

- noinode: build failed due to lack of inodes,

- logerr: hsh-separate-sources(1) failed to analize the build log,

- other: any other error,

- unused: the packages are not listed in SRPM_LISTS (see CONFIGURATION below).

### Stage retries
When a lot of packages are processed, building some of them are often failed --- that´s normal. In that situation the first thing is to investigate the situation, then fix the problem and re-run the stage for the failed packages only.

To help the investigation the following additional targets are available for each stage:

- list-stageN-C[-A]-logs: List paths to the build logs of packages that fall into category C and optionally architecture A in stage N.

- show-stageN-C[-A]-status: Output the stage status log entries related to the packages that fall into category C and optionally architecture A in stage N.

- show-stageN-pkg-status: Output the stage status log entries related to a single package specified with PKG=PKG. For stages I, IV-V the architecture can be additionally limited with ARCH=ARCH.

To re-run the stage for the failed packages only use:

- stageN-retry-C[-A]: Retry the stage N for packages that fall into category C and optionally architecture A.

- stageN-retry-pkgs

If INDEP_LOGS (see CONFIGURATION) is set then a number of such jobs can be run for the same stage in parallel.

To re-run the stage for all packages (failed, done and not tried) use:

•

stageN-rebuild-all: Run stage N from scratch.

When re-running the stage it is possible to alter the configuration of builders, for instance, to change the number of hasher slots --- see BUILDERS in CONFIGURATION below. Additionaly, for Stage V (both 5v and 5o parts) it is possible to run the process for only a subset of architectures: use FOR_ARCHES=<arch1,arch2...> on the command line.

### Partial Stage V targets
For Stage V the following partial subtartets are available:

- stage5v|o-all: Run the stage for not yet tried packages included in all defined architectures.

- stage5v|o-A: Run the stage for not yet tried packages of architecture A.

### Complete stage rebuilds
The run of a stageN target selects and process packages that weren´t processed on that stage yet (that are the packages from noatt category). In order to run the stage for all listed SRPM packages use stageN-rebuild-all target. However, the hsh-separate-sources(1) and srpm-cleanup(1) tools are known to skip the already processed packages anyway. So, to really rebuild all packages delete the existing results with stageN-clean or add -f|--force to the OPTS (see Runtime options below).

### Rebuilds with manual package selection and multistage retries

- stageN-retry-pkgs: Re-run stage N for a specified list of packages. These targets expect name-version-release of packages to be specified on the command line with PKGS=<PKGS...>. In order to rebuild a package forcily pass -f|--force to the OPTS (see Runtime options below).

- reclean-pkgs:

- reclean-and-rebuild-pkgs:

### Dry runs
For each stage target, either the main stage target or any retry or additional target, there is the corresponding -dry-run target available. In the dry-run mode the stage isn´t actually run. Instead of that the list of command lines that would be executed in the normal stage run is printed out.

Moreover, for each stage target the corresponding -dry-run-run target is also available. In that "semi-dry" mode the tools are actually run (on remote hosts, if configured --- see BUILDERS), but each tools is run with --dry-run option.

In both dry-run modes no packages are built, the log files are not written and the stage status is not updated.

### Building external SRPMs
It is possible to rebuild out of the repo SRPM packages passing WITH_SRPMS=EXTRA_DIR to any stage target. However, dist-tags of such packages are undefined!

### Check and export
•

check-rebuild-lists: This target outputs the final statistics after stage IV separated the onto four following categories: done-included-all --- successfully rebuilt packages, included on all architectures; done-xincluded --- successfully rebuilt packages, included on some architectures (for each architecture); not-done-included-all --- failed packages, included on all architectures; not-done-xincluded --- failed packages, included on some architectures (for each architecture).

These package lists constitute a plan for stage V. The successfully rebuilt packages go to V/1 substage and the rest goes to V/2 (rebuilt of the original packages).

The target checks for intersections between the resulting lists and package coverage on each architecture (i. e. the number of all packages included in SRPM_LISTS versus the number of packages, planned for stage V).

•

check-rebuild-results-A: The target outputs statistics similar to check-rebuild-lists, but from stage V point of view: the number of planned verified and original builds can be compared with actual V/1 and V/2 results. The additional feature of the target is that the coverage is calculated twice: first as a plain number of packages successfully rebuilt on stage V, and a second time --- with additional number of packages, failed due to architecture exclusion (i. e. ExcludeArch and ExclusiveArch tags in the RPM spec file).

The statistic is output for the specified architecture A only.

- check-versions: Runs check-included and then check-disttags if DISTTAG_OPTS is defined (see Configuring Stage V).

- check-included: Output the diff between SRPM_LISTS and the packages, actually included into processing on the stages I-V. Normally, the diff should be empty.

- check-disttags: Compares the dist-tags of packages in the reference repository REPO_DIR with dist-tags in the stage V resulting packages in REBUILD_V_DIR and REBUILD_O_DIR directories (see Configuring Stage V). Normally, the diff should be empty.

- export: Copy stage V results from REBUILD_V_DIR and REBUILD_O_DIR directories along with index files into the target directory DESTDIR=DESTDIR (can be specified on the command line or configured in the Makefile). Any extra RPM files in DESTDIR are removed making the source and destination synchronized.

Additional options can be passed to rsync(1) via EXPORT_OPTS=EXPORT_OPTS.

- repo: Constructs an APT repository at OUTREPO (repo by default) with clean, orig, clean-dbg and orig-dbg packages sections.

- export-repo: Copies the repository to DESTDIR. By default the symbolic links to packages are resolved. In order to copy the links as is, override the EXPORT_REPO_OPTS with the empty or an other set of rsync(1) options without -L.

### Clean targets

- statclean: Deletes all temporary files used to calculate statistic values for stageN-status targets.

- clean-stage5v-unused: Delete REBUILD_V_DIR packages that aren´t currently included in SRPM_LISTS.

- clean-stage5o-unused: Delete REBUILD_O_DIR packages that aren´t currently included in SRPM_LISTS.

- clean-indices: Remove the index files, first of all, the DISTTAG_INDEX file used for stage V (see Configuring Stage V). The indices can explicitly be re-created with index-rebuild target.

- stageN-clean: Delete all results and status files of stage N. WARNING! these targets are dangerous! In order to protect the results from accidentally deletion a confirmation is asked.

### Other targets

- list-srpms: Output the list of all included SRPMs.

- show-builders: Output the resulting command-line for the configured BUILDERS (see the CONFIGURATION below) that is used for rebuilding of binary packages (stages I, IV-V).

- show-cleaners: Output the resulting command-line for the configured CLEANERS (see the CONFIGURATION below) that is used to clean-up source packages (stage II).

- show-srpm-builders: Output the resulting command-line for the configured BUILDERS (see the CONFIGURATION below) that is used for rebuilding of source packages (stage III).

### Scripts
•

update-versions.sed: The script that is automatically prepared from BIN_LIST (see Configuring Stage V) and can be used to update version numbers in the existing SRPM lists.

## CONFIGURATION

### General configuration
•

SRPM_LISTS: Defines source package list files for each architecture. Each set of files should be added to SRPM_LISTS using $(call def_srpm_list,arch,files...), where arch is the name of an architecture and files is a space-separated list of files listing source RPM file names (name-version-release.src.rpm) line by line.

For example:

```
SRPM_LISTS = $(call def_srpm_list,ppc64le,lists/alt-sp8-server-latest-ppc64le.iso.srpms)
SRPM_LISTS += $(call def_srpm_list,aarch64,lists/alt-sp8-server-latest-aarch64.iso.srpms lists/alt-sp8-workstation-latest-aarch64.iso.srpms)
SRPM_LISTS += $(call def_srpm_list,armh,lists/alt-sp8-workstation-01-mcom02-latest-armh.img.srpm-list)
SRPM_LISTS += $(call def_srpm_list,i586,lists/alt-sp8-server-latest-i586.iso.srpms lists/alt-sp8-workstation-latest-i586.iso.srpms)
SRPM_LISTS += $(call
def_srpm_list,x86_64,lists/alt-sp8-server-latest-x86_64.iso.srpms
lists/alt-sp8-workstation-latest-x86_64.iso.srpms)
```

•

BUILDERS: Defines the set of local and remote builders (hosts where hsh-separate-sources(1) can be run). Each builder should be added to BUILDERS using $(call def_builder,[user@]hostname,arches...,slots,workdir,repo[,nprofile]), where [user@]hostname defines the name of the remote host and an optional user name to connect with, arches is a space-separated list of architecture names, slots is a list of a range of Hasher slot numbers, workdir is the path to the working directory (on the remote host), repo is the path to package repository (on the remote host) and nprofile is the optional name of a CPU profile file.

All of the def_builder argumentsare match the command line options of hsh-separate-sources(1). In order to build on the local machine use : for the name of the host and don´t specify the user name.

Example:

``` BUILDERS = $(call def_builder,ppc,ppc64le,$(ppc_slots),/tmp/.private/builder/hashers,$(nfs_repo),$(nprocs))

BUILDERS += $(call def_builder,taishan1,aarch64 armh,$(arm_slots),/tmp/.private/builder/hashers,$(nfs_repo),$(nprocs))

BUILDERS += $(call def_builder,builder_new@ivkbuilder,x86_64 i586,$(ivk_slots),/tmp/.private/builder_new/hashers,$(ivk_repo),$(nprocs)) ```

•

CLEANERS: Defines the set of local and remote cleaners (hosts where srpm-cleanup(1) can be run). Each cleaner should be added to CLEANERS using $(call def_cleaner,[user@]hostname,slots,workdir,srpms), where [user@]hostname defines the name of the remote host and an optional user name to connect with, slots is a space-separated list of a range of Hasher slot numbers, workdir is the path to the working directory (on the remote host) and srpms is the path to the directory with SRPM files (on the remote host).

All of the def_cleaner argumentsare match the command line options of srpm-cleanup(1). In order to build on the local machine use : for the name of the host and don´t specify the user name.

Example:

```
CLEANERS = $(call def_cleaner,ppc,1-40,/tmp/.private/builder/hashers,$(nfs_repo)/files/SRPMS)
CLEANERS += $(call def_cleaner,taishan1,1-40,/tmp/.private/builder/hashers,$(nfs_repo)/files/SRPMS)
CLEANERS += $(call def_cleaner,builder_new@ivkbuilder,1-40,/tmp/.private/builder/hashers,$(ivk_repo)/files/SRPMS)
```

•

EXTRA_ARCHES: Specify extra arches of those builders that aren´t currently configured.

### Remote options

- SSHDELAY: Log-in to the next remote host after a delay. Setting this to a positive non-zero value helps against SSH errors when a lot of parallel remote processes are started.

- CLEANUP: Set this to enable --cleanup mode with hsh-separate-sources(1) and srpm-cleanup(1) in order to save space on the remote hosts. Note, that --cleanup is incompatible with --selfie, so the scripts have to be copied to the hosts beforehand (see also Tools).

### Tools

- HSH_SEPARATE_SOURCES: Sets the path to the hsh-separate-sources(1) script on all remote hosts (no customization yet).

- SRPM_CLEANUP: Sets the path to the srpm-cleanup(1) script on all remote hosts (no customization yet).

The default is to use the script from the current directory, then --- the script in PATH.

### Log options

- LOG_SUF: Defines a suffix to use for stage log file names. Using the same stage log file name prevents from running multiple jobs for the same stage (for instace, retries with different options --- see Stage retries) simultaneously. That´s become possible if a different log filename suffix is used with each job. If INDEP_LOGS is set, i.e. not empty (the default) then random suffixes are used.

- INDEP_LOGS: Controls if random LOG_SUF values should be used for each stage run. The flag is set by default (a non empty value).

- BACKUP_LOGS: Set to a non-empty value to disable independent logs and enable making backups of the stage log file on each next stage run (including stage retries). Setting BACKUP_LOGS to a non-empty value prevents from running multiple jobs for the same stage simultaneously.

### Configuring Stage I

- SKIPLIST_DIR: Directory to write the list of unused packages for each processed source package. The default is skip.

- INCLIST_DIR: Directory to write the list of used packages for each processed source package. The default is inc.

- STAGE1_LOG: Log file for Stage I. The default is logs/stage1.log.

- STAGE1_LOGDIR: Directory for Stage I package build logs. The default is logs/stage1.logs.

- STAGE1_STATUS: Status file for Stage I. The default is stage1.status.

### Configuring Stage II

- TAR_DIR: Directory to output TAR packages to. The default is pkgs.

- STAGE2_LOG: Log file for Stage II. The default is logs/stage2.log.

- STAGE2_LOGDIR: Directory for Stage II package build logs. The default is logs/stage2.logs.

- STAGE2_STATUS: Status file for Stage II. The default is stage2.status.

- EXCEPTIONS: A file with the list of exception paths for srpm-cleanup(1) (-x|--exceptions). The default is exceptions.list. The list is also used with Stage IV.

### Configuring Stage III

- SRPM_DIR: Directory to output SRPM packages to. The default is out.

- STAGE3_LOG: Log file for Stage III. The default is logs/stage3.log.

- STAGE3_LOGDIR: Directory for Stage III package build logs. The default is logs/stage3.logs.

- STAGE3_STATUS: Status file for Stage III. The default is stage3.status.

### Configuring Stage IV

- RPM_DIR: Directory to output the resulting RPM packages to. The default is rpms.

- STAGE4_LOG: Log file for Stage IV. The default is logs/stage4.log.

- STAGE4_LOGDIR: Directory for Stage IV package build logs. The default is logs/stage4.logs.

- STAGE4_STATUS: Status file for Stage IV. The default is stage4.status.

- TOOLERANCE: SRPM cleanup verification toolerance, %. The default is 0%.

If EXCEPTIONS (see above) is defined, the name of the file is passed to hsh-separate-sources(1) with -x|--exceptions).

### Configuring Stage V

- REPO_DIR: Path to the reference package repository (on the local host).

- BIN_LIST: Path to the bin.list file in the reference repository on the local host. The default is $(REPO_DIR)/files/list/bin.list.

- DISTTAG_INDEX: The name of the dist-tag index file. The dist-tag index depends on the BIN_LIST and is updated automatically. The default is disttag.index.

- DISTTAG_OPTS: Options to pass to hsh-separate-sources in order to enable dist-tags. The default is --disttag-index="$(DISTTAG_INDEX)".

- REBUILD_OPTS: Additional options to pass to hsh-separate-sources on Stage V. For example, the --with-pre and --with-post options. There is no default value for this option.

- REBUILD_V_DIR: Directory to write the verified, cleaned-up RPM packages to. The default is rebuild.v.

- STAGE5_V_LOG: Log file for Stage V/1. The default is logs/stage5.v.log.

- STAGE5_V_LOGDIR: Directory for Stage V/1 package build logs. The default is logs/stage5.v.logs.

- STAGE5_V_STATUS: Status file for Stage V/1. The default is stage5.v.status.

- STAGE5_V_EXCLUDE_LIST: Name of the file with the list of packages to exclude from Stage V/1. The listed packages are included in Stage V/2 even if they sucessfully passed Stage IV. The default is exclude.list.

- REBUILD_O_DIR: Directory to write the RPM packages resulted from rebuilding of the original SRPM packages, typically --- the packages that failed on Stage IV. The default is rebuild.o.

- STAGE5_O_LOG: Log file for Stage V/2. The default is logs/stage5.o.log.

- STAGE5_O_LOGDIR: Directory for Stage V/2 package build logs. The default is logs/stage5.o.logs.

- STAGE5_O_STATUS: Status file for Stage V/2. The default is stage5.o.status.

### Runtime options

- OPTS: Any command line options to pass to a tool corresponding to the stage.

- FOR_ARCHES: Run the stage (I, IV-V) on the hosts of the specified architectures only. The architectures can be listed separated by spaces or commas.

- PKGS: List of packages to rebuild (stageN-retry-pkgs targets only).

## SEE ALSO
hsh-separate-sources(1), hasher(1), gear(1), hsh(1).

## COPYRIGHT
Copyright (C) 2020 BaseALT /basealt.ru/. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## AUTHOR

- Anton V. Boyarshinov boyarsh@altlinux.org

- Michael Shigorin mike@altlinux.org

- Paul Wolneykien manowar@altlinux.org

## REPORTING BUGS
Report bugs to https://bugzilla.altlinux.org/.