.\"	$OpenBSD: remote.5,v 1.21 2009/10/22 09:22:46 sobrado Exp $
.\"	$NetBSD: remote.5,v 1.4 1997/04/20 00:05:27 mellon Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)remote.5	8.1 (Berkeley) 6/5/93
.\"
.Dd $Mdocdate: October 22 2009 $
.Dt REMOTE 5
.Os
.Sh NAME
.Nm remote
.Nd remote host description file
.Sh DESCRIPTION
The systems known by
.Xr tip 1
and their attributes are stored in an
.Tn ASCII
file which is structured somewhat like the
.Xr termcap 5
file.
Each line in the file provides a description for a single remote host.
Fields are separated by a colon
.Pq Sq \&: .
Lines ending with a
.Dq \e
character immediately followed by a newline are continued on the next line.
.Pp
The first entry is the name(s) of the host system.
If there is more than one name for a system, the names are separated by
vertical bars
.Pq Sq \&| .
After the name of the system comes the fields of the description.
A field name followed by an equal sign
.Pq Sq =
indicates a string value follows.
A field name followed by a pound sign
.Pq Sq #
indicates a following numeric value.
.Pp
Entries named
.Dq tip\&*
.\"and
.\".Dq cu\&*
are used as default entries by
.Xr tip 1
.\"and the
.\".Xr cu 1
.\"interface to
.\".Xr tip 1 ,
as follows.
When
.Xr tip 1
is invoked with only a baud rate, it looks for an entry of the form
.Dq tip Ns Aq baud rate .
E.g.\&
.Ic tip -300
will cause
.Xr tip 1
to look for the system tip300.
.\"When the
.\".Xr cu 1
.\"interface is used, entries of the form
.\".Dq cu300
.\"are used.
.Sh CAPABILITIES
Capabilities are either strings (str), numbers (num), or boolean flags (bool).
A string capability is specified by
.Em capability Ns Ar = Ns Em value ;
for example,
.Dq dv=/dev/harris .
A numeric capability is specified by
.Em capability Ns Ar # Ns Em value ;
for example,
.Dq xa#99 .
A boolean capability is specified by simply listing the capability.
.Bl -tag -width indent
.It Sy \&at
(str)
Auto call unit type.
.It Sy \&be
(bool)
Initialize the
.Xr tip 1
variable
.Dq beautify
to
.Sy on ,
so that non-printable characters will be discarded when scripting.
.It Sy \&br
(num)
The baud rate used in establishing
a connection to the remote host.
This is a decimal number.
The default baud rate is 300 baud.
.It Sy \&cm
(str)
An initial connection message to be sent to the remote host.
For example, if a host is reached through port selector, this
might be set to the appropriate sequence required to switch to the host.
.It Sy \&cu
(str)
Call unit if making a phone call.
Default is the same as the
.Sy dv
field.
.It Sy \&dc
(bool)
This host is directly connected, and
.Xr tip 1
should not expect carrier detect to be high, nor should it exit if
carrier detect drops.
.It Sy \&di
(str)
Disconnect message sent to the host when a disconnect is requested by the user.
.It Sy \&du
(bool)
This host is on a dial-up line.
.It Sy \&dv
(str)
.Tn UNIX
device(s) to open to establish a connection.
If this file refers to a terminal line,
.Xr tip 1
attempts to perform an exclusive open on the device to ensure only
one user at a time has access to the port.
.It Sy \&ec
(bool)
Initialize the
.Xr tip 1
variable
.Dq echocheck
to
.Sy on ,
so that
.Xr tip 1
will synchronize with the remote host during file
transfer by waiting for the last character transmitted to echo.
.It Sy \&el
(str)
Characters marking an end-of-line.
The default is
.Dv NULL .
.Dq ~
escapes are only recognized by
.Xr tip 1
after one of the characters in
.Sy el ,
or after a carriage-return.
.It Sy \&es
(str)
The escape character for
.Xr tip 1 .
The default is
.Dq ~ .
.It Sy \&et
(num)
Number of seconds to wait for an echo response when
.Dq echocheck
mode is on.
The default value is 10 seconds.
.It Sy \&ex
(str)
Set of non-printable characters not to be discarded when scripting
with beautification turned on.
The default value is
.Dq \et\en\eb\ef .
.It Sy \&fo
(str)
Character used to force literal data transmission.
The default value is
.Sq \e020
(^P).
.It Sy \&fs
(str)
Frame size for transfers.
The default frame size is equal to
.Dv BUFSIZ .
.It Sy \&hd
(bool)
The host uses half-duplex communication, local echo should be performed.
.It Sy \&hf
(bool)
Initialize the
.Xr tip 1
variable
.Dq hardwareflow
to
.Sy on ,
so that hardware flow control (CRTSCTS) will be used for the
connection with the remote host.
.It Sy \&ie
(str)
Input end-of-file marks.
The default is
.Dv NULL .
.It Sy \&ld
(num)
The line discipline to use for the remote tty.
The default is to use the
.Xr termios 4
line discipline.
.It Sy \&nb
(bool)
Initialize the
.Xr tip 1
variable
.Dq beautify
to
.Sy off ,
so that non-printable characters will not be discarded when scripting.
.It Sy \&nt
(bool)
Initialize the
.Xr tip 1
variable
.Dq tandem
to
.Sy off ,
so that XON/XOFF flow control will not be used to throttle data
from the remote host.
.It Sy \&nv
(bool)
Initialize the
.Xr tip 1
variable
.Dq verbose
to
.Sy off ,
so that verbose mode will be turned off.
.It Sy \&oe
(str)
Output end-of-file string.
The default is
.Dv NULL .
When
.Xr tip 1
is transferring a file, this string is sent at end-of-file.
.It Sy \&pa
(str)
The type of parity to use when sending data to the host.
This may be one of
.Dq even ,
.Dq odd ,
.Dq none ,
.Dq zero
(always set bit 8 to zero),
or
.Dq one
(always set bit 8 to 1).
The default is no parity.
.It Sy \&pn
(str)
Telephone number(s) for this host.
Either a list of arbitrary dialing strings separated by
commas, or a
.Ql @ .
An at sign,
.Ql @ ,
tells
.Xr tip 1
to search the
.Xr phones 5
database for the list of telephone numbers.
.Pp
For modems or auto-call units that use a
.Ql \&,
in their dialing strings (hayes, courier, t3000)
.Xr tip 1
will convert any
.Ql \&=
in the string to a
.Ql \&,
when dialing.
For modems or auto-call units that use a
.Ql \&=
in their dial strings, (v831),
.Xr tip 1
will convert any
.Ql \&_
to a
.Ql \&=
when dialing.
.It Sy \&pr
(str)
Character that indicates end-of-line on the remote host.
The default value is
.Sq \en .
.It Sy \&ra
(bool)
Initialize the
.Xr tip 1
variable
.Dq raise
to
.Sy on ,
so that lowercase letters are mapped to uppercase before sending
them to the remote host.
.It Sy \&rc
(str)
Character that toggles case-mapping mode.
The default value is
.Dv NULL .
.It Sy \&re
(str)
The file in which to record session scripts.
The default value is
.Pa tip.record .
.It Sy \&rw
(str)
Initialize the
.Xr tip 1
variable
.Dq rawftp
to
.Sy on ,
so that all characters will be sent as is during file transfers.
.It Sy \&sc
(bool)
Initialize the
.Xr tip 1
variable
.Dq script
to
.Sy on ,
so that everything transmitted by the remote host will be recorded.
.It Sy \&ta
(bool)
Initialize the
.Xr tip 1
variable
.Dq tandem
to
.Sy on ,
so that XON/XOFF flow control will be used to throttle data
from the remote host.
.It Sy \&tb
(bool)
Initialize the
.Xr tip 1
variable
.Dq tabexpand
to
.Sy on ,
so that each tab will be expanded to 8 spaces during file transfers.
.It Sy \&tc
(str)
Indicates that the list of capabilities is continued in the named description.
This is used primarily to share common capability information.
.It Sy \&vb
(bool)
Initialize the
.Xr tip 1
variable
.Dq verbose
to
.Sy on ,
so that verbose mode will be turned on.
.El
.Pp
Here is a short example showing the use of the capability continuation
feature:
.Bd -literal -offset indent
UNIX-1200:\e
:dv=/dev/cau0:el=^D^U^C^S^Q^O@:du:at=ventel:ie=#$%:oe=^D:br#1200:
arpavax|ax:\e
:pn=7654321%:tc=UNIX-1200
.Ed
.Sh FILES
.Bl -tag -width /etc/remote -compact
.It Pa /etc/remote
Global database.
.El
.Sh SEE ALSO
.Xr tip 1 ,
.Xr phones 5
.Sh HISTORY
The
.Nm
file format appeared in
.Bx 4.2 .