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.

lexmark_x2600

Supports the Lexmark X2600 series of USB scanners. See sane-lexmark_x2600(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-lexmark_x2600(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.


package: smokeping

title: smokeping_extend(7)

summary: Notes on extending Smokeping

text:
# smokeping_extend(7)

## NAME
smokeping_extend - Notes on extending Smokeping

## OVERVIEW
This document is intended to guide prospective authors in writing new Smokeping probes. It mostly describes the interface between Smokeping and its probe modules. If it seems too complicated to understand, look at the existing modules for examples.

Comments and proposed changes or additions are welcome. Please send them to the smokeping-users mailing list. Patches against the POD source of this document are most appreciated.

## CHOOSING A BASE CLASS
The first thing you should decide is which base class you should use for your probe. For most (if not all) uses it's a choice between Smokeping::probes::base and Smokeping::probes::basefork. The former is intended for probes that can measure their targets all in one go, while the latter is for probing them one at a time, possibly in several concurrent subprocesses.

At the moment, the only probes that use "Smokeping::probes::base" are the FPing derivatives. All the others use "Smokeping::probes::basefork", and chances are you should too. This document will thus concentrate on the latter case.

## SKELETON FILE
The Smokeping::probes::skel module is a non-functional probe that is intended to make a good basis for a new probe module. Copy the file, "lib/probes/skel.pm", to a new name and just fill out the blanks :) Note that the names of real probe modules must start with a capital letter.

## PROBE DOCUMENTATION
The probe documentation is generated from the source code with the smokeping arguments "--man" or "--makepod". The embedded POD documentation should point to this real documentation, so that curious users of the "perldoc" command see what's going on. All the current probes do this.

You should provide the method "pod_hash" that returns a reference to a hash with keys corresponding to the section names you want in the manpage. The supported section names are "name", "overview", "description", "authors", "notes", "bugs", and "see_also". If you don't need a particular section, just leave it out.

The special sections "synopsis" and "variables" are automatically generated from the description of your variables. See below.

Note that if you use 'here documents' ('<<') that have POD markup inside, you should escape the markup so that it doesn't show up in the embedded POD documentation. Most probes do it like this:

```
 my $e = "=";
 my $doc = <<DOC;
 ${e}head1 SECTION TITLE
 DOC
```

## PROBE DESCRIPTION
The probe should offer the "ProbeDesc" method that returns a short description of what it does. This will be used in the graphs produced by the web frontend.

## VARIABLES
All Smokeping probes must define their variables by implementing a "probevars" method for probe-specific variables and a "targetvars" method for target-specific variables. If you don't know the difference between these yet, see smokeping_examples.

(The probes that are derived from "Smokeping::probes::base" don't support target-specific variables, so they only use the "probevars" method.)

The base classes offer these methods too to provide the variables that are common to all the probes (eg. the probe-specific "step" variable and the target-specific "pings" variable. If you don't want to add anything to the base class variables (perhaps because all your variables are of a target-specific nature, so you don't need new probe-specific variables at all), you can leave the corresponding method out and it will be inherited from the base class.

When you do supply your own "probevars" or "targetvars" method, you should combine your variables with those coming from the superclass. There is a convenience method called "_makevars" that does this, and the common idiom is

```
 sub probevars {
        my $class = shift;
        return $class->_makevars($class->SUPER::probevars, {
                # your variables go here
        }
 }
```

The variables are declared in a syntax that comes from the module used for parsing the configuration file, "Config::Grammar". Each variable should be a hash that uses the "special variable keys" documented in Config::Grammar. See "Smokeping::probes::skel" and the other probes for examples.

For reference, here are the keys the hash should have. Much of this is taken straight from the "Config::Grammar" manual.

Keys you must provide

_doc

Description of the variable.

_example

An example value. This will be used in the SYNOPSIS section in the probe manual.

Optional keys

_default

A default value that will be assigned to the variable if none is specified or inherited.

_re

Regular expression upon which the value will be checked.

_re_error

String containing the returned error in case the regular expression doesn't match (if not specified, a generic 'syntax error' message will be returned).

_sub

A function pointer. It is called for every value, with the value passed as its first argument. If the function returns a defined value it is assumed that the test was not successful and an error is generated with the returned string as content.

The "probevars" and "targetvars" methods should return hash references that contain the variable names as keys and the hashes described above as values. In addition the "Config::Grammar" special section key "_mandatory" is supported and should contain a reference to a list of mandatory variables. The "_makevars" method is aware of this special key and merges the mandatory lists in its arguments. Note that no other "Config::Grammar" special section keys are supported.

## INITIALIZATION
If you must do something at probe initialization time, like check that the external program you're going to use behaves as you expect, you should do it in the "new" method. You should probably also take care that you don't run the tests needlessly while in CGI mode. The usual way to do this is to test for $ENV{SERVER_SOFTWARE}. See the "Smokeping::probes::skel" module for an example.

## PINGING
All the real action happens in the "pingone" method (or, for "Smokeping::probes::base"-derived probes, in the "ping" method.) The arguments for "pingone" are $self, the module instance (since this is a method) and $target, the target to be probed.

You can access the probe-specific variables here via the "$self->{properties}" hash and the target-specific ones via the "$target->{vars}" hash. You get the number of pings needed for the target via the "pings" method: "my $count = $self->pings($target)".

You should return a sorted array of the latency times measured. If a ping fails, don't put anything in the array.

That's it, you're done!

## EXAMPLE CONFIGURATIONS
If you would like to provide a documented example configuration for your probe (in addition to the automatically generated SYNOPSIS section in the probe manual), you can do so by adding it to the Smokeping::Examples module. Look for the 'examples' subroutine and add your example there.

Future versions of Smokeping might provide a way to embed examples in the probe modules too. The author's motivation for implementing this would be greatly increased by even a single demand for it, so please speak up if you think you'd use it.

## TIMEOUT HANDLING
If you deal with timeouts (for example because your program offers a parameter for specifying the timeout for the pings), you should know a few things.

First, there's timeout logic in "Smokeping::probes::basefork" that kills the probe when the timeout is reached. By default the timeout is (# of pings * 5 seconds) + 1 second. If you expect that your pings can take longer, you should modify the default value of the probe-specific variable "timeout". This would be done like this:

```
 sub probevars {
        my $class = shift;
        my $h = $class->SUPER::probevars;
        $h->{timeout}{_default} = 10; # override the superclass default
        return $class->_makevars($h, {
                # your variables go here
        }
 }
```

If you want to provide a target-specific "timeout" setting, you should delete the probe-specific variable and be sure to provide a default for your target-specific one. See eg. "Smokeping::probes::AnotherDNS" for an example of how this is done.

Providing a target-specific "timeout" will make the timeout in "Smokeping::probes::basefork" be (# of pings * the maximum timeout of all targets) + 1 second. The 1 second is added so that the own timeout logic of the probe has time to kick in even in the worst case (ie. all pings are lost) before "Smokeping::probes::basefork" starts killing the processes.

## COPYRIGHT
Copyright 2005 by Niko Tyni.

## LICENSE
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 Foundation; 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.

## AUTHOR
Niko Tyni <ntyni@iki.fi>

## BUGS
This document makes writing new probes look much harder than it really is.

## SEE ALSO
The other Smokeping documents, especially smokeping_config.

branch: sisyphus


title: smokeping_install(7)

summary: How to install SmokePing

text:
# smokeping_install(7)

## NAME
smokeping_install - How to install SmokePing

## OVERVIEW
This document explains how to setup SmokePing at your site.

## DESCRIPTION

### Prerequisites
SmokePing does not stand alone. It relies on various other tools and services being present. Apart from a Unix OS and a working Perl installation you need the following components:

RRDtool 1.2.x or later

Smokeping uses RRDtool for logging and graphing. If your linux distro provides an rrdtool package with perl support, use this. If you want to get the latest and greatest version, compile your own: <http://oss.oetiker.ch/rrdtool/> Ubuntu:

```
 sudo apt install rrdtool librrds-perl libssl-dev

```

RedHat:

```
 sudo yum install rrdtool perl-rrdtool openssl-devel

```

FPing (optional)

Go to <http://www.fping.org/> to grab a copy. Note that fping must be installed setuid root. It seems that older versions of fping report round trip times in 0.1 milliseconds instead of 1 milliseconds as advertised ... SmokePing tries to figure this out. It tells you when it starts ... let me know if it gets it wrong.

EchoPing (Optional)

<https://github.com/bortzmeyer/echoping/> You need this to run the EchoPing probes

Curl (Optional)

<http://curl.haxx.se/> You need this for the Curl probe.

dig (Optional)

<http://www.isc.org/sw/bind/> You need this for the DNS probe.

SSH (Optional)

<http://www.openssh.org/> You need this for the SSH probe.

Webserver

<http://httpd.apache.org/> Well I won't get much into this. The important thing is, to have a webserver which allows you to run CGI and preferably FastCGI scripts. If you are using Apache I strongly recommend using the suexec system for running CGI scripts as a particular user.

See <http://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html> and <http://httpd.apache.org/docs/2.2/mod/mod_suexec.html> for more information on this.

Perl 5.10.1 or later.

If you still have an older version, maybe have a look at perlbrew. Ubuntu:

```
 sudo apt install perl

```

RedHat:

```
 sudo yum install perl-core

```

### Installation
Once the tools listed above are in place, you can start setting up SmokePing itself. Unpack the tar archive and run the included configure script:

```
 ./configure --prefix=/opt/smokeping
```

Configure will verify that all the required perl modules are available. If some are missing it will tell you to run the module build script. Just follow the instructions on screen and then run configure again. Once it completes, you can run

```
 make install
```

to finish your setup.

### Configuration
Use the etc/config.dist file as a template to create your own smokeping configuration file. See smokeping_config for details.

Installing the webinterface

Copy the content of the PREFIX/htdocs directory to the place where your webserver expects its data. Maybe to /var/www/smokeping. Edit the smokeping.fcgi script to point to your smokeping_cgi script.

If you have no FastCGI support in your webserver, you may want to use the smokeping.cgi script.

etc/basepage.html

Edit the html template to your liking. Please do not remove the link to the SmokePing counter and my name from the template. The content of the template will be rendered by smokeping.cgi. This means that all embedded links must be relative to smokeping.cgi. If you are using HTTP authentication, then the template variable "authuser" will be populated from the $ENV{REMOTE_USER} environment variable.

etc/smokemail

If you are going to use the DYNAMIC IP support, customize the contents of this file.

### Starting the Smokeping Daemon
With all the scaffolding in place, you can now launch the smokeping daemon and have it gather data for you. First you may want to run it in debug mode to see what it is doing

```
 ./bin/smokeping --config=/opt/smokeping/etc/config --debug
```

once all is well, start it up as a daemon. I would recommend you enable the logfile option so that you can see if it runs into trouble.

```
 ./bin/smokeping --config=/opt/smokeping/etc/config --logfile=smoke.log
```

Once the system works, you may want to put a SmokePing startup script into your /etc/init.d tree. Check out smokeping for further information.

You can now open the smokeping.cgi webpage to look at your data.

See the smokeping_cgi documentation on how to setup the smokeping web interface.

## COPYRIGHT
Copyright (c) 2001, 2011 by Tobias Oetiker. All right reserved.

## LICENSE
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 Foundation; 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.

## AUTHOR
Tobias Oetiker <tobi@oetiker.ch>


title: smokeping_master_slave(7)

text:
# smokeping_master_slave(7)

## NAME
smokeping_master_slave - How to run multiple distributed instances of SmokePing

## OVERVIEW
Normally smokeping probes run their tests from the host where smokeping runs to some target host and monitor the latency of the connection between the two.

The Master/Slave concept enables all smokeping probes to run remotely. The use case for this is to measure the overall connectivity in a network. If you are interested in checking that your central DNS server or your file server works for everyone, you could setup several smokeping instances checking up on on the two servers from multiple locations within your network. With the Master/Slave smokeping configuration this process becomes much simpler, as one smokeping master server can control multiple slaves.

All monitoring data is stored and presented on the server, but collected by the slaves. The slaves will also get their configuration information from the master, so that you just have to maintain the master server configuration file and the rest is taken care of automatically.

## DESCRIPTION

### Architecture
The slaves communicate with the master smokeping server via the normal smokeping web interface. On initial startup each slave connects to the master server and asks for its assignments. When the slave has done a round of probing it connects to the master again to deliver the results.

If the assignment for a slave changes, the master will tell the slave after the slave has delivered its results.

The master and the slaves sign their messages by supplying an HMAC-MD5 code (RFC 2104) of the message and a shared secret. Optionally the whole communication can run over ssl.

```
    [slave 1]     [slave 2]      [slave 3]
        |             |              |
        +-------+     |     +--------+
                |     |     |
                v     v     v
              +---------------+
              |    master     |
              +---------------+
```

The slave is a normal smokeping instance setup where the configuration comes from the master instead of a local configuration file. The slave tries to contact the master server after every round of probing, supplying its results. If the master server can not be reached, the results will be sent to the server together with the next round of results. Results will be stored in a file in Perl storable form so that they survive a restart of the smokeping instance.

### Master Configuration
To configure a master/slave setup, add a slaves section to your smokeping configuration file. Each slave has a section in the slaves part of the master configuration file. The section name must match the hostname of the slave. If some configuration parameter must be set to a special value for the slave, use an override section to configure this.

The slave names must be the names the hosts think they have, not their outside hostnames or ip addresses or anything like that. When the slave calls the master to get its config or report its measurements it will tell the master its 'hostname'. This together with the shared secret is used to authenticate and identify who is who.

```
 *** Slaves ***
 secrets=/etc/smokeping/slavesecrets.conf
 +slave1
 display_name=erul22
 location=India
 color=ff0000
 ++override
 Probes.FPing.binary = /usr/bin/fping
 ...
```

Then in the targets section you can define slaves at every level. Again the settings get inherited by lower order targets and can be overwritten anywhere in the tree.

A slave will then get the appropriate configuration assigned by the server.

```
 *** Targets ***
 slaves = slave1 slave2
 ...
 +dest1
 slaves =
 ...
 +dest2
 slaves = slave1
 ...
 +dest3
 ...
```

The data from the slaves will be stored in TargetName~SlaveName.rrd. So the example above would create the following files:

```
 dest1.rrd
 dest2.rrd
 dest2~slave1.rrd
 dest3.rrd
 dest3~slave1.rrd
 dest3~slave2.rrd
```

The slavesecrets.conf file contains a colon separated list of hostnames and secrets.

```
 host1:secret1
 host2:secret2
```

### Slave Configuration
A smokeping slave setup has no configuration file. It just needs to know that it runs in slave-mode and its secret. The secret is stored in a file for optimal protection. By default the persistent data cache will be located in /tmp/smokeping.$USER.cache.

```
 ./smokeping --master-url=http://smokeping/smokeping.cgi \
             --cache-dir=/var/smokeping/ \
             --shared-secret=/var/smokeping/secret.txt
```

The secret.txt file contains a single word, the secret of this slave. It is NOT the same as the slavesecrets.conf file the master uses.

## SECURITY CONSIDERATIONS
The master effectively has full access to slave hosts as the user running the slave smokeping instance. The configuration is transferred as Perl code that is evaluated on the slave. While this is done inside a restricted "Safe" compartment, there are various ways that a malicious master could embed arbitrary commands in the configuration and get them to run when the slave probes its targets.

The strength of the shared secret is thus of paramount importance. Brute forcing the secret would enable a man-in-the-middle to inject a malicious new configuration and compromise the slave.

## COPYRIGHT
Copyright (c) 2007 by Tobias Oetiker, OETIKER+PARTNER AG. All right reserved.

## LICENSE
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 Foundation; 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.

## AUTHOR
Tobias Oetiker <tobi@oetiker.ch>


title: smokeping_upgrade(7)

summary: Notes on upgrading Smokeping

text:
# smokeping_upgrade(7)

## NAME
smokeping_upgrade - Notes on upgrading Smokeping

## OVERVIEW
This document tries to list incompatible or otherwise user-visible changes in Smokeping versions, with instructions on how to fix any possible problems. It also sporadically mentions new features and the like.

The document currently starts with changes from 1.34 to 1.37. If you run into problems with upgrading from earlier versions, please send a description of the problems, preferably with notes on how to fix them, to the "smokeping-users" mailing list, so they can be added to this document. The same applies to any problems you find with current versions that are not documented here, of course. Patch submissions against the POD source of this file are most appreciated.

If a version is not listed, there are no known problems in upgrading to it from the previous release.

An official list of changes with each release can be found in the CHANGES file in the Smokeping distribution. This document tries to complement that with upgrading instructions etc.

## 2.4.2 to 2.4.3
To fix zooming for FF3.5 I prototype and scriptaculous have been updated. To complete the fix you have to update your basepage.html too and include effects in the scriptaculous load line

```
 cropper/lib/scriptaculous.js?load=builder,effects,dragdrop
```

## 2.3.6 to 2.4.0
The new SmokeTrace tool was added to SmokePing. For setup instructions read the smoketrace manual page.

## 2.3.3 to 2.3.4
The communication protocol between master and slave has been made more secure. This requires that BOTH master and slave are upgraded to continue working.

## 2.2.x to 2.3.x
2.3.0 is mainly about new features. Check out the reference documentation on hierarchies and the target properties parents, hidden and nomasterpoll.

The only thing you have to take a look at, is the file basepage.html.dist which got some new css properties. Without them the results of the new filter function will look quite bad.

## 2.1.x to 2.2.0

### LWP Dependency
The new master/slave functionality needs the LWP::UserAgent module from CPAN. Currently the dependency is not optional; you'll need the module even if you are only running one Smokeping instance.

## 2.0.9 to 2.1.0

### Echoping 6 support
This is the first Smokeping version that fully supports echoping 6. Earlier versions of the EchoPingHttp probes don't work with echoping 6 because of a command line incompatibility. (Echoping 5 is still supported, of course.)

This version also introduces three new probes using the new echoping plugin interface introduced in version 6:

- EchoPingDNS

- EchoPingLDAP

- EchoPingWhois

See the smokeping_examples document for simple examples of using these probes.

### New method in base.pm (if you write your own probes)
The base.pm module defines the method ProbeUnit. Override this if your Probe does not return 'Seconds'. See the FTPtransfer.pm for inspiration.

## 2.0.8 to 2.0.9

### FPing
The 'timeout' variable removed in 2.0.5 has been brought back. It is used to give the "fping" command the "-t" parameter, which apparently affects the timeout of the last ping in the counting ("-C") mode used by Smokeping.

## 2.0.5 to 2.0.6

### CGI self-referring links (again)
The way Smokeping creates the self-referring links was changed once more. See the section under '2.0.4 to 2.0.5' for a description of the previous change.

The behaviour is now customizable via the "linkstyle" variable in the "General" section of the configuration file. The default is now "relative", creating links like . I hope this works for everybody, but if it doesn't, see smokeping_config for the alternatives.

## 2.0.4 to 2.0.5

### FPing
The 'timeout' variable has been removed. It was used to give the "fping" command the "-t" parameter, but as this parameter is only effective in "fping"'s default mode, while Smokeping uses the counting mode ("-c"), it never actually did anything.

### CGI self-referring links
The way Smokeping creates the self-referring links was changed. The old behaviour used the script name but not the host part, resulting in links like . The new behaviour uses the "cgiurl" variable: the links are always absolute like .

## 2.0.1 to 2.0.2

### Edge-triggered alerts
The alert notifications can now optionally be sent only when the state of the alert changes. This means that only the first match of the alert generates a notification, subsequent matches don't. When the alert is cleared, ie. there's no match anymore, another notification is sent.

This behaviour is enabled by the "edgetrigger" variable in the "Alerts" section. The old behaviour (which sends a notification on each match) is the default.

## 1.40 to 2.0
The biggest change with the 2.0 release is that the configuration file is now parsed much more strictly. This should result in (hopefully understandable) error messages making the configuration less of the trial-and-error variety than it used to be. It also automates the generation of the configuration documentation from the source code, so the docs are now more accurate.

A smaller change worth mentioning is the inclusion of the tSmoke script (contributed by Dan McGinn-Combs) for sending summary emails on daily and weekly system status. Note that it needs the new 'tmail' variable to be defined in the config file.

### CONFIGURATION
The configuration syntax has stayed mostly the same, except for the issues below.

PROBE_CONF

The PROBE_CONF subsections have been deprecated. All the target-specific variables are now configured in the same section as the target is. Just deleting the ++ PROBE_CONF

lines should fix this (for any number of '+', obviously.)

The existence of a PROBE_CONF section makes smokeping exit with an error message at parse time.

Note for distributors: these lines could easily be removed automatically during upgrade.

Variable order

The "probe" variable must now be set before any variables that depend on the selected probe. This is because setting "probe" modifies the grammar of the rest of the section dynamically at parse time. Additionally, "probe" must now precede "host", for reasons that have to do with the current implementation of mandatory variable checking.

Both of these errors are recognized at parse time and produce error messages accordingly.

Note for distributors: the "smokeping" command now has a new '--check' option that can be used to verify the syntax of the configuration file. It might be a good idea to do this on upgrade and give the user an explanatory note if the verification fails.

Target-specific variables in the Probes section

This is not an incompatible change, but it is mentioned here nevertheless. Target-specific variables can now be specified in the Probes section as well, and the values given become defaults for all the targets.

Timeouts

The "timeout" variable in the Probes section is now the maximum time expected for one ping to take. Previously it was the maximum time allowed for all the pings to one target. This is an incompatible change, but the code now works in the way it was documented to work even in 1.38. Those probes offering a target-specific "timeout" variable will get a default for it from the Probes section, as noted in the previous item. This should ensure that probes that enforce the ping timeout themselves (most do) will not get killed due to timeout before they have a chance to do it.

Matchers

The matcher modules have been renamed to start with a capital letter, to differentiate the actual modules from the base classes. You have to capitalize the matcher name in the pattern definition accordingly.

Minimum number of pings

The "pings" variable now has an enforced minimum value of 3, as the whole design of Smokeping is based on the idea of sending several probes and measuring and visualizing the variation between them.

RRD parameter checking

Smokeping now checks at startup that the parameters of any existing RRD files match those specified in the configuration file. If there is a discrepancy, it will try to fix the situation and refuse to start if it can't. This situation is most likely to happen if you have modified the "pings" variable in your configuration file. You'll then have to delete the old RRD file or somehow convert it to use the new parameters. The "rrdtune" command might be helpful here.

Configurable location for DYNAMIC-related files

There is now a new configuration variable, "dyndir", that can be used to specify the location of the DYNAMIC-related files (.adr and .snmp). These files used to be kept under "datadir" along with the RRD files, but since they need to be writable by the web server, it may be useful to separate these. If "dyndir" is not specified, Smokeping will use the "datadir" value as the default. This should ensure that no existing setups will break.

In addition to this, some probes have had minor incompatible changes to their configuration.

RemoteFPing

The "rbinary" variable is now mandatory. This is a side effect from a bigger change: the probe is now derived from the FPing probe and supports all the variables FPing does.

FPing6

This probe is also now derived from FPing and supports all the variables FPing does.

Curl

The URL that will be used is now specified with the variable "urlformat" instead of "url". The new variable can (and usually should) include a placeholder for the "host" variable of each target as "%host%", eg. "urlformat = http://%host%/". The new variable is mandatory. The change was made to fix the confusing situation where the "host" variable was required for each actual target, but it didn't actually have any effect (as the server to be probed came from the "url" variable.)

Timeouts are now recognized properly by looking at the curl exit code. The default timeout of this probe has been raised to 10 seconds.

The command line is now executed without an intervening /bin/sh, and so quotes are not needed anymore around the User-Agent string (the "agent" parameter). Smokeping will complain if it notices quotes around the string.

Any extra arguments for "curl" can now be specified in the "extraargs" variable.

EchoPingHttp

The default timeout of this probe has been raised to 10 seconds.

EchoPingHttps

The default timeout of this probe has been raised to 10 seconds.

EchoPingIcp

The "url" variable is now mandatory, as the old default "/" didn't make sense because it's relative rather than absolute.

LDAP

The "filter" variable is now mandatory, as Net::LDAP bails out without it. The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly (it's now the minimum time between two queries rather than the time slept between the end of one and the start of the another.)

Radius

The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly. See the LDAP explanation above.

AnotherDNS

The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly. See the LDAP explanation above. Additionally, the time is now specified in seconds rather than microseconds.

AnotherSSH

The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly. See the LDAP explanation above. Additionally, the time is now specified in seconds rather than microseconds.

TelnetIOSPing

The name of this probe was changed: it now starts with a capital letter like all the others do. The "target" variable was removed. The target should now be specified in the "host" variable, like it is with all the other probes.

### CGI::Carp module version
The recommended version for CGI::Carp is now at least 1.24, included in CGI.pm-2.82 and the Perl standard distribution starting from 5.8.1. See the smokeping_install document.

## 1.38 to 1.40
The new navigation feature

The big visible difference between 1.38 and 1.40 is the new browser navigation feature: when clicking on the graphs in detail view you can select different time ranges for the graph. The creation of this feature has been sponsored by BeverlyCorp.com.

## 1.34 to 1.37
The RemoteFPing probe

The configuration of this probe was moved from the Targets section to the Probes section, as all the variables are really probe-specific. The moved variables were "rhost", "rbinary" and "rhost".

Logging changes

The "smokeping" daemon now warns at startup if syslog support is not turned on in the config file. This is because many diagnostic messages will otherwise get lost.

Concurrent probes

Each probe now runs in its own process, instead of them all running sequentially in one process. This makes it possible to specify different step lengths for different probes. You can get the old behaviour back by setting 'concurrentprobes = no'.

## COPYRIGHT
Copyright 2005 by Niko Tyni.

## LICENSE
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 Foundation; 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.

## AUTHOR
Niko Tyni <ntyni@iki.fi>

## SEE ALSO
The other Smokeping documents, especially smokeping_config.


sndio

package: sndio

title: sndio(7)

summary: audio and MIDI device descriptors

text:
# sndio(7)

## NAME
sndio — audio and MIDI device descriptors

## DESCRIPTION
Programs access audio and MIDI hardware using the sndio library. It allows both access through the sndiod(8) server and raw access to the hardware. The audio device or MIDI port, as well as the access method, are designated by the sndio descriptor. It is provided by the user with the program device selection method, or with the AUDIODEVICE and MIDIDEVICE environment variables if there's no device selection method.

Usually, programs access the hardware via the sndiod(8) server, because raw access to the hardware is exclusive and requires additional privileges. The sndiod(8) server supports multiple connections at a time, allowing multiple programs to use the hardware concurrently. It performs the necessary audio processing on the fly to overcome any incompatibility between software and hardware. Connections to sndiod(8) may also be established through the network, including from virtual machines.

The sndiod(8) server exposes MIDI thru ports, allowing one program to send MIDI data to other programs, for instance to allow a sequencer to send events to a synthesizer.

Additionally, sndiod(8) exposes a MIDI port used to control audio programs using standard MIDI Machine Control (MMC), MIDI Time Code (MTC), and master volume messages.

### Server device descriptors
From the user's perspective, every audio device or MIDI port exposed by sndiod(8) has a descriptor of the form:

```
type[@hostname][,servnum]/[devnum|option]
```

This information is used by programs to determine how to access the audio device or MIDI port.

type

The type of the audio device or MIDI port. Possible values are:

snd

Audio device exposed by sndiod(8).

midithru

MIDI thru port created with sndiod(8).

midi

MIDI port exposed by sndiod(8).

hostname

The hostname or address where the remote sndiod(8) server to connect to is running.

servnum

The number of the sndiod(8) server to connect to, corresponding to the integer specified using the -U option of sndiod(8). Useful only if multiple sndiod(8) servers are running on the same system.

devnum

Device number. It corresponds to the number of the corresponding -f or -q option on the sndiod(8) command line.

option

Corresponds to the sub-device string registered using the -s option of sndiod(8).

### Raw device descriptors
Every raw audio device or MIDI port has a descriptor of the form:

type/devnum

The type can be either rsnd or rmidi. The rsnd/0 device descriptor accesses the /dev/audio0 device, rsnd/1 accesses /dev/audio1, and so on. Similarly, rmidi/0 accesses /dev/rmidi0 and so on.

### Default Audio and MIDI devices
When no audio device descriptor is provided to a program or when the reserved word default is used as the audio device, the program will use the one specified in the AUDIODEVICE, AUDIOPLAYDEVICE and/or AUDIORECDEVICE environment variables. If they are not set, the program first tries to connect to snd/default. If that fails, it then tries to use rsnd/0.

Similarly, if no MIDI descriptor is provided to a program or when the reserved word default is passed as the device descriptor, the program uses the one specified in the MIDIDEVICE environment variable. If it is not set, the program first tries to connect to midithru/0. If that fails, it then tries to use rmidi/0. As long as sndiod(8) is running, this allows programs to exchange MIDI data on machines with no MIDI hardware by default, e.g. a MIDI player could use a software synthesizer with no manual configuration required.

### Authentication
For privacy reasons only one user may have connections to sndiod(8) at a given time. Users are identified by their session cookie, which is automatically generated by audio or MIDI programs upon the first connection to the server. The cookie is stored in $HOME/.sndio/cookie and contains 128 bits of raw random data.

If a session needs to be shared between multiple users, they can connect to the server using the same cookie.

## ENVIRONMENT
AUDIODEVICE

Audio device descriptor to use when no descriptor is explicitly specified to a program.

AUDIOPLAYDEVICE

Audio device descriptor to use for play-only mode when no descriptor is explicitly specified to a program. Overrides AUDIODEVICE.

AUDIORECDEVICE

Audio device descriptor to use for record-only mode when no descriptor is explicitly specified to a program. Overrides AUDIODEVICE.

MIDIDEVICE

MIDI port descriptor to use when no descriptor is explicitly specified to a program.

These environment variables are ignored by sndio if the program has the set-user-ID or set-group-ID bits set.

## FILES
~/.sndio/cookie

User's session authentication cookie.

/dev/audioN

Raw audio devices.

/dev/rmidiN

Raw MIDI ports.

## EXAMPLES
snd/0

Audio device referred to by the first -f option of sndiod(8).

snd/rear

Sub-device registered with “-s rear”.

midithru/0

First MIDI thru port created with sndiod(8).

default

Default audio or MIDI device.

rsnd/0

Direct hardware access to /dev/audio0.

rmidi/5

Direct hardware access to /dev/rmidi5.

## SEE ALSO
aucat(1), midicat(1), sndioctl(1), mio_open(3), sio_open(3), sioctl_open(3), audio(4), midi(4), sndiod(8)


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.