Go to the first, previous, next, last section, table of contents.

Runtime configuration for mgetty: `mgetty.config'

Mgetty works quite well with the compiled-in defaults (it has been the only way to configure it for a long time), but that's quite unflexible, and especially if you use different modem types, it's extremely unhandy. The built-in defaults can be modified by command line options, but that's not perfect either, because it makes `/etc/inittab' entries very long and difficult to read.

If compiled with config file support (define MGETTY_CONFIG in `policy.h'), mgetty can use a configuration file, quite similar to those which "Taylor UUCP" uses, which make dynamic setup far easier.

The config file is usually located in `/usr/local/etc/mgetty+sendfax/' and named `mgetty.config'. Its format is very simple. Each line contains one keyword, and possibly arguments for it, separated by whitespace. Empty lines, and comment lines (lines starting with `#') are allowed.

The config file is grouped into port-specific sections, separated by port <tty-name> lines. Everything before the first port line specifies global defaults, everything between two port statements specifies configuration items valid only for exactly this device. Let me show you an example:

# global defaults:
# fax station id is always the same
fax-id ++49-89-1234
# per port stuff
port tty1a
# This modem can't fax
modem-type data

port tty2a
# more verbose logging for this modem
debug 9

The data part of each line, following the keyword, can be a string (in most cases), a chat sequence (a series of strings, separated by whitespace, that specify the "modem talk" to do. It starts with "expect" string, then "send", then "expect" again, and so on), an integer (interpreted as decimal, octal or hexadecimal, depending on the leading character [1-9/0/0x]), or boolean (`y(es)' or `t(rue)' vs. `n(o)' or `f(alse)'). If no argument is specified, this will be considered "value not set" (if allowed) or "error" (if value is mandatory), except for boolean values. In that case, it's interpreted as `true'.

Many of those configuration items can be overriden from the command line. In that case, command line options take precedence over configuration file settings (and those take precedence over built-in defaults). In many cases, the built-in defaults can be set in `policy.h'.

The available configuration items are (command line options, if available, given in brackets):

• speed [-s] port speed Specify, as integer value, the port speed to use. Default is DEFAULT_PORTSPEED. If the given speed is not valid, mgetty complains loudly and exits.
• switchbd fax recv. speed Some modems, mainly Rockwell chipsets, switch to 19200 bps when entering fax mode. Others may need other speed switches (but I know none). If your modem is Rockwell based, try switchbd 19200 if fax reception doesn't work. (Warning: if this is set wrongly, fax reception will definitely fail. For most sane modems, you do not need this.). Default is FAX_RECV_SWITCHBD.
• direct yes/no [-r] Tells mgetty that it is running on a direct line. Mgetty won't try to initialize any modem, nor will it wait for `RING'. It will just wait for any character, and then output the issue file and login prompt. This option is used if you want to connect to machines via nullmodem cable. Default is no, since mgetty is designed for modems...
• blocking yes/no [-b] Tells mgetty to open the device in `blocking' mode, that is, the open() system call won't succeed until carrier detect is set. This is set if mgetty is called as getty. I'm not sure whether it's very useful, but I include it for completeness. Default is no.
• port-owner username/userid If set, mgetty will chown the tty line to the given username (you can specify a string or an integer uid, but the integer must be valid). This is highly recommended for security purposes: only give port access to those users you trust not to misuse your modem lines! Default is PORT_OWNER.
• port-group groupname/gid If set, mgetty will chgrp the tty line to this group id (which can be given as group name, or as integer gid). If it's not given, or not valid, the primary group id of `port-owner' will be used. Default is PORT_GROUP.
• port-mode permissons Specifies the permissions to chmod the device to. Never make a modem device world-accessible, better use `0660' or even `0600'. Default is PORT_MODE.
• toggle-dtr yes/no Tells mgetty whether it should lower the DTR line upon startup to reset modem. Default is `yes', but some (few) modems react allergic to that and crash.
• toggle-dtr-waittime msecs Specifies the time to hold the DTR line low. Default is 500 milliseconds.
• data-only yes/no [-D] Tells mgetty to forget about faxing and only use the data part of the modem. Default is `false'. You need this if your modem can't distinguish incoming fax and data calls.
• fax-only yes/no [-F] Tells mgetty to put the modem in fax-only mode. You need this if your modem can't distinguish incoming fax and data calls, but you need fax more important than data; and you need it if you want to disable data calls for security reasons (this could be achieved via `login.config' as well) Watch out: if you have setup some unusual answer-chat, incoming calls might still come through. So check your setup!
• modem-type [-C] mtype Specifies the kind of modem connected to the port. Default is DEFAULT_MODEMTYPE. Valid options are:
  • auto Mgetty will detect the modem type itself (which may occasionally be not desirable, or it may fail on old modem equipment). Mgetty will use the ATI command to find out the modem type, and select the proper fax class accordingly. If that fails (unknown modem type), mgetty will try class 2.0 and then class 2.
  • c2.0 Modem is a class 2.0 fax mode. Works better than class 2, if both are available, because its better standardized. Known to work with USR, ZyXEL 1496 and 2864 series, and ELSA modems.
  • cls2 Modem is a class 2 fax modem, mgetty will not try class 2.0.
  • c2.1 Modem conforms to the new ITU T.32 standard (class 2.1). To my knowledge, there are no such modems available yet, but supporting them will be easy as class 2.1 is very similar to class 2.0.
  • cls1 Modem can only do class 1 fax. NOT IMPLEMENTED YET. (And not recommended anyway).
  • c1.0 Modem can do class 1 fax conforming to ITU T.31 standard. This isn't much better than class 1 (use class 2 / 2.0 if available!), but is better standardized. NOT IMPLEMENTED YET.
  • cls2ok (obsolete, use modem-quirks 02)
  • data Do not try fax initialization, same as if `-D' given.
  There is no way (yet) to tell mgetty to use only fax mode and refuse data calls with this option, use the fax-only true statement for that.
• modem-quirks bitmask Some modems have a very peculiar interpretation of the fax standards. Some of the internal operations of mgetty+sendfax can be adapted to that. The argument is a number, constructed from valies in `fax_lib.h', one bit per "quirk". Usually you won't need this option, because those modems really needing it are auto-detected and handled properly anyway. Right now, the following quirks are defined:

  0x01  leave the modem in class 2 mode instead of switching
        to class 0 before sending ATA (you might try this if
        adaptive fax/data answer doesn't work).
  0x02  class 2 bit order is correct (MultiTech) - unimplemented
  0x04  do not trust +FPTS:x,lc,blc values
  0x08  do not wait for XON character when sending pages
  0x20  AT+FCC/+FMINSP bug workaround for (very) old USR Courier V.32
  0x40  display incoming informations about 'non standard frames' - this
        might be necessary on some USR modems to work around logic bugs
  

• init-chat [-m] expect send expect send ... Tells mgetty the chat sequence to use for initializing the modem. Warning: the sequence starts with expect, which will in most cases be `""' (nothing). This ordering was chosen because UUCP does it this way, and I wanted to avoid confusion here. Example:

  init-chat "" ATQ0E1V1H0 OK ATL0M0S0=0 OK AT&K3 OK
  

• force-init-chat expect send expect send ... In some cases, the modem can get stuck in a mode where it won't react to a simple AT command. Usually this happens because the modem is set to ignore a DTR drop and still has a data connection to the other side. If you use a voice modem, it could be stuck in voice mode. In these situations, the normal init-chat will time out, because the modem won't send the proper responses back. To get the modem back into a sane state, you can use the force-init-chat chat sequence. The default setup will send the DLE ETX characters, to get voice modems back to life, and then the (pause)+++(pause)ATH0 sequence to get the modem back from data mode to command mode. You could prepend this sequence to init-chat (it wouldn't harm), but especially the pauses around the +++ sequence makes this undesirable slow.
• post-init-chat expect send expect send ... Some modems forget parts of their settings when going from data to fax mode and back during modem initialization. For example, some USR models forget the settings of "Caller ID delivery" (AT#CID=1), and some ELSA modems forget their current DTE port speed when going from voice to data mode, thus leading to RING messages being delivered with the wrong baud rate. For those modems, you can use this command to set up some AT commands that are executed after all other fax and voice initialization has been done. Be careful with what you do! If you send an ATZ (modem reset) or something similar here, all your fax/voice settings will be lost!
• modem-check-time seconds Some modems have the nasty tendency to crash silently. With this option, you tell mgetty to check every seconds seconds with a simple `AT...OK' sequence whether the modem still reacts. If not, mgetty will restart itself and do a full modem reset. Default is MODEM_CHECK_TIME
• rings [-n] nnn Sets the number of RING messages to wait for, before mgetty picks up the phone. Default is 1. Warning: if your modem auto-answers, for whatever reason, set this to something different than the value set with ATS0=mmm, otherwise the modems autoanswer and mgettys manual answer will collide (most modems hang up if a command is received during auto-answer)
• msn-list msn1 msn2 msn3... If you have an ISDN modem that signals the called party number (MSN) to the host, you can use this statement to map the MSN numbers to distictive RINGs. The MSN called will be compared the list, and the first match is used for the distinctive RING number. The list is searched from left to right. This is known to work with ELSA and ZyXEL ISDN terminal adaptors.
• get-cnd-chat chat sequence This is needed if you have a modem that supports "caller ID" detection, but needs a special command to get the CID information. Right now, this is only needed for some ELINK ISDN adaptors (see section Elink ISDN Terminal Adaptors 293, 310, 393 with X.75 and V.110), most other CID-capable modems send the CID on their own and don't need this. Don't forget to set rings to at least 2, otherwise the CID grabbing code won't work.
• cnd-program pathname Specify a program to be run before answering an incoming call. Use this if the static Caller ID selection in CNDFILE (policy.h) is not sufficient, or if you want to use the Caller ID data for other purposes (displaying, for example). See section Using Caller-ID to selectively accept or reject calls.
• answer-chat chat sequence This is the command sequence that is used to answer a phone call. Usually you can leave it at the default ` "" ATA CONNECT \c \r ', but for some modems you need `ATS0=1' in place of `ATA' (ATA not allowed). The extra `\r' expect string is needed that the code can grab the full CONNECT xyz\r string. It will work without the \r, but then the logging information will be less detailed. Right now, \r won't work at all, it's not implemented yet. Don't use it.
• answer-chat-timeout secs During the answer-chat, each "expect" string must be seen in the time specified here. Default is 80 seconds. This time should be at least some 5 seconds longer than the time set with the ATS7=... modem setup command.
• autobauding yes/no [-a] Some modems switch their DTE line speed to the communication line speed after connecting, e.g., after sending `CONNECT 2400', the modem switches to 2400 bps. Newer modems usually have a switch to "lock" a DTE baud rate, which is strongly recommended. If your modem insists on doing this speed switch, setting autobauding to true will make mgetty behave accordingly.
• ringback yes/no [-R] If you have to put your modem and your telephone on the same phone line, you can switch on "ringback" or "ring-twice". This means, mgetty won't answer the phone on the first call, but remember the call, and pick up on the second call (if it comes in the time specified by ringback-time).
• ringback-time secs This setting specifies how much time may pass between the first and the second call if "ringback" is active. Default is 30 seconds.
• ignore-carrier If your Modem does not assert the DCD (carrier detect) line, or the serial port or cable or serial driver is broken, it is possible that mgetty or login will block after a successful CONNECT (that means: everything seems to work, but suddenly nothing is sent to the port anymore. Depending on the operating system used, this can be before printing the `/etc/issue' file or not before printing the `password:' prompt. To work around this, you can switch off the carrier detection in the kernel: set ignore-carrier true. Default is false. WARNING: If you use this, your system won't be able to detect when a caller just hangs up instead of cleanly logging out. This may result in hanging modems, etc.
• issue-file [-i] file This is the file printed before the login prompt. Default is `/etc/issue'. Some special characters are substituted by connect speed, date, etc. - see below (login-prompt) for a list.
• prompt-waittime msecs This specifies how long mgetty will wait for modem and line to settle down before printing issue file and login prompt. Default is 500 milliseconds.
• login-prompt [-p] prompt This specifies the login prompt that mgetty will output. Some special characters in this string (and in the issue file, btw) are recognized and replaced by something else:
  • @ system name
  • \n newline
  • \r carriage return
  • \g bell
  • \b backspace (ascii 010)
  • \f form feed (ascii 013)
  • \t TAB
  • \P (and \L) port name (e.g. ttyS0)
  • \C date and time, in "ctime()" format
  • \I Connection string (e.g. 2400/REL)
  • \N (and \U) number of users currently logged in
  • \S Port speed (e.g. 38400)
  • \D current date in dd/mm/yy format
  • \T current time in hh:mm:ss format
  • \Y CallerID of the current caller
  • \digit character with the specified octal code
  The maximum lenght of the login prompt is limited to 140 characters (after expansion).
• login-time secs This specifies the maximum time the user can take to log in. If no login has occured after that time, mgetty will hang up. Default is MAX_LOGIN_TIME from `policy.h'.
• fido-send-emsi yes/no Only relevant when mgetty was compiled with -DFIDO. Controls whether mgetty should send a FidoNET style "EMSI_REQA77E" packet before prompting for login. Default is on. Switch this off if you have FIDO support compiled in but experience weird problems with some PPP clients (or users!) being confused by that string.
• login-conf-file pathname Specifies the path and filename of the 'login.config' file that tells mgetty which program to call for login. See the example login.config file to get some ideas what to do with it. The file name given will be ignored for security reasons if the file is not owned by 'root', or is readable or writeable by anybody else than 'root' (that is, it must be mode 0600 or 0200).
• fax-id [-I] local fax number This sets the fax station ID used in fax mode to identify your site to the caller (usually this is simply your fax phone number). Default is FAX_STATION_ID.
• fax-server-file [-S] poll control file Specifies the fax file(s) that is to be sent if someone else calls your modem in fax polling mode, that is, the caller receives a document. Normally, the file given is a text file, containing the list of G3 files to send to the calling machine, one file per line. Comment lines (starting with "#") are ignored. For backward compatibility, mgetty does check whether the named file is a G3 file itself, in which case this file is sent directly (but then, you can only send one page). Not all modems support fax poll server mode, I know that the ZyXEL and MultiTech do, and USR does not.
• diskspace [-k] kbytes This setting tells mgetty the minimum amount of disk space that has to be available in the fax spool directory for fax reception to be allowed. Default is 1 Mbyte.
• notify mail address This is the address that will get mails if a fax is received. Not fully tested.
• fax-owner username/uid
• fax-group groupname/gid
• fax-mode perms Similar to port-owner/group/mode, these settings specify the owner, group and file mode mgetty will use for incoming faxes. Defaults are taken from FAX_IN_OWNER, FAX_IN_GROUP, and FAX_FILE_MODE.
• fax-spool-in dir1:dir2:dirn Specifies a directory, or list of directories, where incoming faxes are saved. Multiple directories are tried in order until, the first one that has enough disk space and is writeable is used. The default setting is taken from FAX_SPOOL_IN in the Makefile usually /var/spool/fax/incoming:/tmp (/tmp is used as fallback).
• debug [-x] debug level This sets the amount of logging mgetty will do. A good value is 4, more details are seen with 5, and 9 is really noisy. Try it! The log data is written to the file specified by LOG_PATH in `policy.h', usually this is something like `/var/log/mgetty.ttyxx'.
• gettydefs gd tag If you use the gettdefs feature of mgetty -- which is not recommended! -- this specifies the gettydefs tag to use for the given line. See man gettydefs, man mgettydefs.
• term terminal type If you are on Linux or similar OSes that have getty set the TERM=xxx terminal type variable, and have no other method to set it (e.g. from `/etc/profile' or `$HOME/.profile'), mgetty can do it for you. Just specify `term vt100' or so. I don't think it's a good idea to specify the terminal type on a per line base (what if all your callers use different terminal types?), so the default is unset.

Go to the first, previous, next, last section, table of contents.