MINICOM(1)

NAME
minicom - friendly serial communication program

SYNOPSIS
minicom [-somlz] [-c on|off] [-d entry] [-a on|off]
[-t term] [-p pty] [configuration]

DESCRIPTION
minicom is a communication program which somewhat resembles the shareware program TELIX but is free with source code and runs under most unices. Features include dialing directory with auto-redial, support for UUCP-style lock files on serial devices, a seperate script language interpreter, capture to file, multiple users with individual configurations, and more.

COMMAND-LINE

-s  Setup. This is allowed for root only. When this option is used, minicom does not initialize, but puts you directly into the configuration menu. This is very handy if minicom refuses to start up because your system has changed, or for the first time you run minicom. For most systems, reasonable defaults are already compiled in.

-o  Do not initialize. Minicom will skip the initialization code. This option is handy if you quitted from minicom without resetting, and then want to restart a session. It is potentially dangerous though: no check for lock files etc. is made, so a normal user could interfere with things like uucp... Maybe this will be taken out later. For now it is assumed, that users who are given access to a modem are responsible enough for their actions.

-m  Override command-key with the Meta or ALT key. This can also be configured in one of minicom's menus, but if you use different terminals all the time, of which some don't have a Meta or ALT key, it's handy to set the default command key to Ctrl-A and use this option when you have a keyboard supporting Meta or ALT keys. Minicom assumes that your Meta key sends the ESC prefix, not the other variant that sets the highest bit of the character.

-M  Same as -m, but assumes that your Meta key sets the 8th bit of the character high (sends 128 + character code).

-z  Use terminal status line. This only works on terminals that support it and that have the relevant information in their termcap or terminfo database entry.

-l  Literal translation of characters with the high bit set. With this flag on, minicom will not try to translate the IBM line characters to ASCII, but passes them straight trough. Many PC-unix clones will display them correctly without translation (Linux in a special mode, Coherent and Sco).

-a  Attribute usage. Some terminals, notably televideo's, have a rotten attribute handling (serial instead of parallel). By default, minicom uses '-a on', but if you are using such a terminal you can (must!) supply the option '-a off'. The trailing 'on' or 'off' is needed.

-t  Terminal type. With this flag, you can override the environment TERM variable. This is handy for use in the MINICOM environment variable; one can create a special termcap entry for use with minicom on the console, that initializes the screen to raw mode so that in conjunction with the -l flag, the IBM line characters are displayed untranslated.

-c  Color usage. Some terminals (such as the Linux console) support color with the standard ANSI escape sequences. Because there is apparently no termcap support for color, these escape sequences are hard-coded into minicom. Therefore this option is off by default. You can turn it on with '-c on'. This, and the '-m' option, are good candidates to put into the MINICOM environment variable.

-d  Dial an entry from the dialing directory on startup. You can specify an index number, but also a substring of the name of the entry.

-p  Pseudo terminal to use. This overrrides the terminal port defined in the configuration files, but only if it is a pseudo tty. The filename supplied must be of the form (/dev/)tty[p-z][0-f].

    When minicom starts, it first searches the MINICOM environment variable for command-line arguments, which can be over-ridden on the command line. Thus, if you have done

        MINICOM='-m -c on'
        export MINICOM

    or the equivalent, and start minicom, minicom will assume that your terminal has a Meta or <ALT> key and that color is supported. If you then log in from a terminal without color support, and you have set MINICOM in your startup (.profile or equivalent) file, and don't want to re-set your environment variable, you can type 'minicom -c off' and run without color support for that session.

configuration
    The configuration argument is more interesting. Normally, minicom gets its defaults from a file called "minirc.dfl". If you however give an argument to minicom, it will try to get its defaults from a file called "minirc.configuration". So it is possible to create multiple configuration files, for different ports, different users etc. Most sensible is to use device names, such as tty1, tty64, sio2 etc. If a user creates his own configuration file, it will show up in his home directory as '.minirc.dfl'.

USE
Minicom is windows-based. To popup a window with the function you want, press Control-A (from now on, we will use C-A to mean Control-A), and then the function key (a-z or A-Z). By pressing C-A first and then 'z', a help screen comes up with a short summary of all commands. This escape key can be altered when minicom is configured (-s option or C-A O), but we'll stick to Control-A for now.

For every menu the next keys can be used:
UP  arrow-up or 'k'
DOWN
    arrow-down or 'j'
LEFT
    arrow-left or 'h'
RIGHT
    arrow-right or 'l'
CHOOSE
    Enter
CANCEL
    ESCape.

The screen is divided into two portions: the upper 24 lines are the terminal-emulator screen. In this window, ANSI or VT100 escape sequences are interpreted. If there is a line left at the bottom, a status line is placed there. If this is not possible the status line will be showed every time you press C-A. On terminals that have a special status line that will be used if the termcap information is complete and the -k flag has been given.

Possible commands are listed next, in alphabetical order.
C-A Pressing C-A a second time will just send a C-A to the remote system. If you have changed your "escape character" to something other than C-A, this works analogously for that character.
A   Toggle 'Add Linefeed' on/off. If it is on, a linefeed is added before every carriage return displayed on the screen.
B   Gives you a scroll back buffer. You can scroll up with u, down with d, a page up with b, a page down with f, and if you have them the arrow and page up/page down keys can also be used.
C   Clears the screen.
D   Dial a number, or go to the dialing directory.
E   Toggle local echo on and off (if your version of minicom supports it).
F   A break signal is sent to the modem.
G   Run script (Go). Runs a login script.
H   Hangup.
I   Toggle the type of escape sequence that the cursor keys send between normal and applications mode. (See also the comment about the status line below).
J   Jump to a shell. On return, the whole screen will be redrawn.
K   Clears the screen, runs kermit and redraws the screen upon return.
L   Turn Capture file on off. If turned on, all output sent to the screen will be captured in the file too.
M   Sends the modem initialization string.
O   Configure minicom. Puts you in the configuration menu.
P   Communication Parameters. Allows you to change the baudrate, parity and number of bits.
Q   Exit minicom without resetting the modem. If macros changed and were not saved, you will have a chance to do so.
R   Recieve files. Choose from various protocols (external).
S   Send files. Ditto.
T   Choose Terminal emulation: Ansi(color) or vt100. You can also change the backspace key here and turn the status line on or off.
W   Toggle linewrap on/off.
X   Exit minicom, reset modem. If macros changed and were not saved, you will have a chance to do so.
Z   Pop up the help screen.

DIALING DIRECTORY
By pressing C-A D the program puts you in the dialing directory. You can add, delete or edit entries. By choosing "dial" the phone number of the highlighted entry will be dialed. While the modem is dialing, you can press escape to cancel dialing. Any other key will close the dial window, but won't cancel the dialing itself. Your dialing directory will be saved into a the file ".dialdir" in your home directory. You can scroll up and down with the arrow keys, but you can also scroll complete pages by pressing the PageUp or PageDown key. If you don't have those, use Control-B (Backward) and Control-F (Forward). You can use the space bar to tag a number of entries and minicom will rotate trough this list if a connection can't be made.

The "edit" menu speaks for itself, but I will discuss it briefly here.
A - Name
    The name for this entry
B - Number
    and its telephone number.
C - Dial string #
    Which specific dial string you want to use to connect. There are three different dial strings (prefixes and suffixes) that can be configured in the Modem and dialing menu.
D - Local echo
    can be on or off for this system (if your version of minicom supports it).
E - Script
    The script that must be executed after a succesfull connection is made (see the manual for runscript)
F - Username
    The username that is passed to the runscript program. It is passed in the environment string "$LOGIN".
G - Password
    The password is passed as "$PASS".
H - Terminal Emulation
    Use ANSI or VT100 emulation.
I - Backspace key sends
    What code (Backspace or Delete) the backspace key sends.
J - Line settings
    Baudrate, bits and parity to use for this connection. You can choose current for the speed, so that it will use whatever speed is being used at that moment (useful if you have multiple modems).

CONFIGURATION
By pressing C-A O you will be thrown into the setup menu. Most settings there can be changed by everyone, but some are restricted to root only. Those priviliged settings are marked with a star (*) here.

Filenames and paths
    This menu defines your default directories.
    A - upload
        where the uploaded files go to.
    B - download
        Yup, you guessed it.
    C - script
        Where you keep your login scripts.
    D - Script program
        Which program to use as the script interpreter. Defaults to the program "runscript", but if you want to use something else (eg, /bin/sh or "expect") it is possible. Stdin and stdout are connected to the modem, stderr to the screen.
        If the path is relative (ie, does not start with a slash) then it's relative to your home directory, except for the script interpreter.
    E - Kermit program
        Where to find the executable for kermit, and it's options. Some simple macro's can be used on the command line: '%l' is expanded to the complete filename of the dial out-device, and '%b' is expanded to the current baudrate.

File Transfer Protocols
    Protocols defined here will show up when C-A s/r is pressed. "Name" is the name that will show up in the menu. "Program" is the path to the protocol. "NeedName" defines if the program needs an argument, eg. a file to be transmitted. Up/Down defines if this entry should show up in the upload or the download menu. Fullscr defines if the program should run full screen, or that minicom will only show it's stderr in a window. Finally, IO-Red defines if minicom should attach the program's standard in and output to the modem port or not. The old sz and rz are not full screen, and have IO-Red set. However, there are curses based versions of at least rz that do not want their stdin and stdout redirected, and run full screen. All file transfer protocols are run with the UID of the user, and not with UID=root. '%l' and '%b' can be used on the command line as with kermit.

Serial port setup
    *A - Serial device
        /dev/tty1 for most people. /dev/cua<n> or /dev/modem under linux.
    *B - Lock file location
        On most systems This should be /usr/spool/uucp. Linux systems use /var/lock. If this directory does not exist, minicom will not attempt to use lockfiles.
    *C - Callin program
        If you have a uugetty or something on your serial port, it could be that you want a program to be run to switch the modem cq. port into dialin/dialout mode. This is the program to get into dialin mode.
    *D - Callout program
        And this to get into dialout mode.
    E - Baud/Par/Bits
        Default parameters at startup.

    If one of the entries is left blank, it will not be used. So if you don't care about locking, and don't have a getty running on your modemline, entries B - D should be left blank. Be warned! The callin and callout programs are run with the effective user id of "root", eg 0!

Modem and Dialing
    Here, the parameters for your modem are defined. I will not explain this further because the defaults are for generic Hayes modems, and should work always. This file is not a Hayes tutorial :-) The only thing worth noticing is that control characters can be sent by prefixing them with a '^', in which '^^' means '^' itself. Some options however, don't have much to do with the modem but more with the behaviour of minicom itself:
    M - Dial time
        The number of seconds before minicom times out if no connection is established.
    N - Delay before redial
        Minicom will redial if no connection was made, but it first waits some time.
    O - Number of tries
        Maximum number of times that minicom attempts to dial.
    P - Autobaud detect
        If this is on, minicom tries to match the dialed party's speed.
    Q - Drop DTR to hangup
        Normally minicom hangs up by sending a Hayes-type hangup sequence but if your system supports it, it can also hangup by dropping the DTR line.
    R - Modem has DCD line
        If your modem, and your O/S both support the DCD line (that goes 'high' when a connection is made) minicom will use it.

    Note that a special exception is made for this menu: every user can change all parameters here, but they will not be saved.

Screen and keyboard
    A - Command key is
        the 'Hot Key' that brings you into command mode. If this is set to 'ALT' or 'meta key', you can directly call commands by alt-key instead of HotKey-key.
    B - Backspace key sends
        There still are some systems that want a VT100 to send DEL instead of BS. With this option you can enable that stupidity. (Eh, it's even on by default...)
    C - Status line is
        Enabled or disabled. Some slow terminals (for example, X-terminals) cause the status line to jump "up and down" when scrolling, so you can turn it off if desired. It will still be shown in command-mode.
    D - Alarm sound
        If turned on, minicom will sound an alarm (on the console only) after a succesfull connection and when up/downloading is complete.
    E - Foreground Color (menu)
        indicates the foreground color to use for all the configuration windows in minicom.
    F - Background Color (menu)
        indicates the background color to use for all the configuration windows in minicom. Note that minicom will not allow you to set forground and background colors to the same value.
    G - Foreground Color (term)
        indicates the foreground color to use in the terminal window.
    H - Background Color (term)
        indicates the background color to use in the terminal window. Note that minicom will not allow you to set forground and background colors to the same value.
    I - Foreground Color (stat)
        indicates the foreground color to use in for the status bar.
    J - Background Color (stat)
        indicates the color to use in for the status bar. Note that minicom will allow you to set the status bar's forground and background colors to the same value. This will effectively make the status bar invisible but if these are your intensions, please see the option
    K - History buffer size
        The number of lines to keep in the history buffer (for backscrolling).
    L - Macros file
        is the full path to the file that holds macros. Macros allow you to define a string to be sent when you press a certain key. In minicom, you may define F1 through F10 to send up to 256 characters [this is set at compile time]. The filename you specify is verified as soon as you hit ENTER. If you do not have permissions to create the specified file, an error message will so indicate and you will be forced to re-edit the filename. If you are permitted to create the file, minicom checks to see if it already exists. If so, it assumes it's a macro file and reads it in. If it isn't, well, it's your problem :-) If the file does not exist, the filename is accepted.
    M - Edit Macros
        opens up a new window which allows you to edit the F1 through F10 macros.
    N - Macros enabled
        - Yes or No. If macros are disabled, the F1-F10 keys will just send the VT100/VT220 function key escape sequences.

Edit Macros
    Here, the macros for F1 through F10 are defined. The bottom of the window shows a legend of character combinations that have special meaning. They allow you to enter special control characters with plain text by prefixing them with a '^', in which '^^' means '^' itself. You can send a 1 second delay with the '^~' code. This is useful when you are trying to login after ftp'ing or telnet'ing somewhere. To edit a macro, press the number (or letter for F10) and you will be moved to the end of the macro. When editing the line, you may use the left & right arrows, Home & End keys, Delete & BackSpace, and ESC and RETURN. ESC cancels any changes made while ENTER accepts the changes.

Save setup as dfl
    Save the parameters as the default for the next time the program is started. Instead of dfl, any other parameter name may appear, depending on which one was used when the program was started.

Save setup as..
    Save the parameters under a special name. Whenever Minicom is started with this name as an argument, it will use these parameters. This option is of course priviliged to root.

Exit
    Escape from this menu without saving. This can also be done with ESC.

Exit from minicom
    Only root will see this menu entry, if he/she started minicom with the '-s' option. This way, it is possible to change the configuration without actually running minicom.

STATUS LINE
The status line has several indicators, that speak for themselves. The mysterious APP or CUR indicator probably needs explanation. The VT100 cursor keys can be in two modes: applications mode and cursor mode. This is controlled by an escape sequence. If you find that the cursor keys do not work in, say, vi when you're logged in using minicom then you can see with this indicator whether the cursor keys are in applications or cursor mode. You can toggle the two with the C-A I key. If the cursor keys then work, it's probably an error in the remote system's termcap initialization strings (is).

SECURITY ISSUES
Since Minicom runs setuid root, you probably want to restrict access to it. This is possible by using a configuration file in the same directory as the default files, called "minicom.users". The syntax of this file is as following:

    <username> <configuration> [configuration...]

To allow user 'miquels' to use the default configuration, enter the following line into "minicom.users":

    miquels dfl

If you want users to be able to use more than the default configurations, just add the names of those configurations behind the user name. If no configuration is given behind the username, minicom assumes that the user has access to all configurations.

MISC
If minicom is hung, kill it with SIGTERM . (This means kill -15, or since sigterm is default, just plain "kill <minicompid>". This will cause a graceful exit of minicom, doing resets and everything.

Since a lot of escape sequences begin with ESC (Arrow up is ESC [ A), Minicom does not know if the escape character it gets is you pressing the escape key, or part of a sequence.

An old version of Minicom, V1.2, solved this in a rather crude way: to get the escape key, you had to press it twice.

As of release 1.3 this has bettered a little: now a 1-second timeout is builtin, like in vi. For systems that have the select() system call the timeout is 0.5 seconds. And... surprise: a special Linux-dependant hack :-) was added. Now, minicom can separate the escape key and escape-sequences. To see how dirty this was done, look into wkeys.c. But it works like a charm!

FILES
Minicom keeps it's configuration files in one directory, usually /var/lib/minicom, /usr/local/etc or /etc. To find out what default directory minicom has compiled in, issue the command minicom -h. You'll probably also find the demo files for runscript(1) there.

minicom.users
minirc.*
$HOME/.minirc.*
$HOME/.dialdir

VERSION
Minicom is now up to version 1.71.

AUTHORS
The author of minicom is Miquel van Smoorenburg (miquels@drinkel.ow.org, miquels@cistron.nl)

Most of this man page is copied, with corrections, from the original minicom README, but some pieces and the corrections are by Michael K. Johnson (johnsonm@stolaf.edu).