Telnet Environment Option
A Telnet option that lets a client pass environment variables such as USER and DISPLAY to the server at login.
Borman, D., Ed., "Telnet Environment Option", RFC 1408, DOI 10.17487/RFC1408, January 1993, <https://www.rfc-editor.org/info/rfc1408>.
@misc{rfc1408,
series = {Request for Comments},
number = 1408,
howpublished = {RFC 1408},
publisher = {RFC Editor},
doi = {10.17487/RFC1408},
url = {https://www.rfc-editor.org/info/rfc1408},
author = {D. Borman},
title = {{Telnet Environment Option}},
pagetotal = 7,
year = 1993,
month = jan,
} RFC text
Contents
Network Working Group D. Borman, Editor
Request for Comments: 1408 Cray Research, Inc.
January 1993
Telnet Environment Option
Status of this Memo
This RFC specifies an IAB standards track protocol for the Internet
community, and requests discussion and suggestions for improvements.
Please refer to the current edition of the "IAB Official Protocol
Standards" for the standardization state and status of this protocol.
Distribution of this memo is unlimited.
Abstract
This document specifies a mechanism for passing environment
information between a telnet client and server. Use of this
mechanism enables a telnet user to propagate configuration
information to a remote host when connecting.
1. Command Names and Codes
ENVIRON 36
IS 0
SEND 1
INFO 2
VAR 0
VALUE 1
ESC 2
USERVAR 3
2. Command Meanings
IAC WILL ENVIRON
The sender of this command is willing to send environment
variables.
IAC WONT ENVIRON
The sender of this command refuses to send environment variables.
IAC DO ENVIRON
The sender of this command is willing to receive environment
variables.
IAC DONT ENVIRON
The sender of this command refuses to accept environment
variables.
IAC SB ENVIRON SEND [ type ... [ type ... [ ... ] ] ] IAC SE
The sender of this command requests that the remote side send its
environment variables. The "type" may be either VAR or USERVAR,
to indicate either well known or user variable names. Only the
side that is DO ENVIRON may initiate a SEND command. If a list of
variables is specified, then only those variables should be sent.
If no list is specified, then the default environment, of both
well known and user defined variables, should be sent. If one of
the variables has no name, then all the variables of that type
(well known or user defined) in the default environment should be
sent.
IAC SB ENVIRON IS type ... [ VALUE ... ] [ type ... [ VALUE ... ] [
The sender of this command is sending environment variables. This
command is sent in response to a SEND request. Only the side that
is WILL ENVIRON may send an IS command. The "type"/VALUE pairs
must be returned in the same order as the SEND request specified
them, and there must be a response for each "type ..." explicitly
requested. The "type" will be VAR or USERVAR. Multiple
environment variables may be sent. The characters following a
"type" up to the next "type" or VALUE specify the variable name.
The characters following a VALUE up to the next "type" specify the
value of the variable. If a "type" is not followed by a VALUE
(e.g., by another VAR, USERVAR, or IAC SE) then that variable is
undefined. If a VALUE is immediately followed by a "type" or IAC,
then the variable is defined, but has no value. If an IAC is
contained between the IS and the IAC SE, it must be sent as IAC
IAC. If a variable or a value contains a VAR, it must be sent as
ESC VAR.
If a variable or a value contains a USERVAR, it must be sent as
ESC USERVAR. If a variable or a value contains a VALUE, it must
be sent as ESC VALUE. If a variable or a value contains an ESC,
it must be sent as ESC ESC.
IAC SB ENVIRON INFO type ... [ VALUE ... ] [ type ... [ VALUE ... ] [
The sender of this command is sending information about environment
variables that have changed. It is identical to the IS command,
except that the command is INFO instead of IS. Only the side that
is WILL ENVIRON may send an INFO command. The INFO command is not
to be used to send initial information; the SEND/IS sequence is to
be used for that. The INFO command is to be used to propagate
changes in environment variables, and may be spontaneously
generated.
3. Default Specification
The default specification for this option is
WONT ENVIRON
DONT ENVIRON
meaning there will not be any exchange of environment information.
4. Motivation
Many operating systems have startup information and environment
variables that contain information that should be propagated to
remote machines when Telnet connections are established. Rather than
create a new Telnet option each time someone comes up with some new
information that they need propagated through a Telnet session, but
that the Telnet session itself doesn't really need to know about,
this generic information option can be used.
5. Well Known Variables
USER This variable is used to transmit the user or account
name that the client wishes to log into on the remote
system. The format of the value the USER variable is
system dependent, as determined by the remote system.
JOB This variable is used to transmit the job ID that the
client wishes to use when logging into the remote system.
The format of the value the JOB variable is system
dependent, as determined by the remote system.
ACCT This variable is used to transmit the account ID that the
client wishes to use when logging into the remote system.
The format of the value the ACCT variable is system
dependent, as determined by the remote system.
PRINTER This variable is used to identify the default location
for printer output. Because there does not currently
exist a standard way of naming a printer on a network,
the format of this variable is currently undefined.
SYSTEMTYPE This is used to transmit the type of operating system on
the system that sends this variable. It value is
identical to the value of the SYSTEM (SYST) command in
FTP [2]. The format of the value shall have as its
first word one of the system names listed in the
current version of the Assigned Numbers document [3].
DISPLAY This variable is used to transmit the X display location
of the client. The format for the value of the DISPLAY
variable is:
<host>:<dispnum>[.<screennum>]
This information is identical to the information passed
using the Telnet X-DISPLAY-LOCATION option. If both the
DISPLAY environment variable, and the
X-DISPLAY-LOCATION option[4] are received, and they
contain conflicting information, the most recently
received information received should be used.
Because it is impossible to anticipate all variables that users may
wish to exchange, the USERVAR type is provided to allow users to
transmit arbitrary variable/value pairs. The use of an additional
type allows implementations to distinguish between values derived by
the remote host software and values supplied by the user. Paranoid
implementations will most likely treat both types with an equal level
of distrust. The results of a name-space collision between a well-
known and a user variable are implementation specific.
6. Implementation Rules
WILL and DO are used only at the beginning of the connection to
obtain and grant permission for future negotiations.
Once the two hosts have exchanged a WILL and a DO, the sender of the
DO ENVIRON is free to request that environment variables be sent.
Only the sender of the DO may send requests (IAC SB ENVIRON SEND IAC
SE) and only the sender of the WILL may transmit actual environment
information (via the IAC SB ENVIRON IS ... IAC SE command). Though
this option may be used at anytime throughout the life of the telnet
connection, the exchange of environment information will usually
happen at the startup of the connection. This is because many
operating systems only have mechanisms for propagating environment
information at process creation, so the information is needed before
the user logs in. In this section, anything that is in quotes is
shorthand for a string of ASCII values. For example, "joe" means the
three octet sequence (in decimal) 106 111 101.
The receiving host is not required to put all variables that it
receives into the environment. For example, if the client should
send across USERVAR "TERM" VALUE "xterm" as an environment variable,
and the TERMINAL-TYPE [1] option has already been used to determine
the terminal type, the server may safely ignore the TERM variable.
Also, some startup information may be used in other ways; for
example, the values for "USER", "ACCT" and "PROJ" values might be
used to decide which account to log into, and might never be put into
the users environment. In general, if the server has already
determined the value of an environment variable by some more accurate
means, or if it does not understand a variable name, it may ignore
the value sent in the ENVIRON option. The server may also prefer to
just put all unknown information into the users environment. This is
the suggested method of implementation, because it allows the user
the most flexibility.
The following is an example of use of the option:
Host1 Host2
IAC DO ENVIRON
IAC WILL ENVIRON
[ Host1 is now free to request environment information ]
IAC SB ENVIRON SEND VAR "USER"
VAR "ACCT" VAR USERVAR IAC SE
[ The server has now explicitly asked for the USER and ACCT
variables, the default set of well known environment variables,
and the default set of user defined variables. Note that the
client includes the USER information twice; once because it was
explicitly asked for, and once because it is part of the
default environment. ]
IAC SB ENVIRON IS VAR "USER"
VALUE "joe" VAR "ACCT" VALUE
"kernel" VAR "USER" VALUE "joe"
VAR "DISPLAY" VALUE "foo:0.0"
USERVAR "SHELL" VALUE "/bin/csh"
IAC SE
It is legal for a client to respond with an empty environment (no
data between the IAC SB and IAC SE) when no well-defined or user
variables are currently defined. For example:
IAC SB ENVIRON IS IAC SE
is a valid response to any of the following:
IAC SB ENVIRON SEND IAC SE
IAC SB ENVIRON SEND VAR IAC SE
IAC SB ENVIRON SEND USERVAR IAC SE
IAC SB ENVIRON SEND VAR USERVAR IAC SE
(The last example is equivalent to the first...)
It is expected that any implementation that supports the Telnet
ENVIRON option will support all of this specification.
7. Security Concerns
It is important for an implementor of the ENVIRON option to
understand the interaction of setting options and the
login/authentication process. Specifically careful analysis should be
done to determine which variables are "safe" to set prior to having
the client login. An example of a bad choice would be permitting a
variable to be changed that allows an intruder to circumvent or
compromise the login/authentication program itself.
8. References
[1] VanBokkelen, J., "Telnet Terminal-Type Option", RFC 1091, FTP
Software, Inc., February 1989.
[2] Postel, J. and J. Reynolds, "File Transfer Protocol (FTP)", STD
9, RFC 959, USC/Information Sciences Institute, October 1985.
[3] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1340,
USC/Information Sciences Institute, July 1992.
[4] Marcy, G., "Telnet X Display Location Option", RFC 1096, Carnegie
Mellon University, March 1989.
Security Considerations
Security issues are discussed in Section 7.
Author's Address
David A. Borman, Editor
Cray Research, Inc.
655F Lone Oak Drive
Eagan, MN 55123
Phone: (612) 452-6650
EMail: dab@CRAY.COM
Mailing List: telnet-ietf@CRAY.COM
Chair's Address
The working group can be contacted via the current chair:
Steve Alexander
INTERACTIVE Systems Corporation
1901 North Naper Boulevard
Naperville, IL 60563-8895
Phone: (708) 505-9100 x256
EMail: stevea@isc.com
AI ELI5
On this page
§4Why a Generic Environment Option
Many operating systems have startup information and environment variables that should be passed to a remote machine when a Telnet connection is set up. Instead of defining a new Telnet option every time someone needs some new piece of information carried along, RFC 1408 defines one generic option for it.
The Telnet session itself does not need to understand the information. It only carries it. The default is WONT ENVIRON and DONT ENVIRON, which means no environment information is exchanged unless both sides agree.
Instead of making a new form for every little thing, there is one big blank form where you can write any setting you want to share.
§2Commands and Codes
The option is called ENVIRON and has the code 36. Inside a subnegotiation there are three commands: IS (0), SEND (1) and INFO (2). Variable entries use the type markers VAR (0), VALUE (1), ESC (2) and USERVAR (3).
The side that sent DO ENVIRON may send a SEND request, optionally naming the variables it wants. With no list, the default environment of both well known and user defined variables should be sent. Only the side that sent WILL ENVIRON may answer with IS, and it must reply in the same order as the request and give a response for each variable explicitly requested.
A variable name follows a VAR or USERVAR marker, and its value follows a VALUE marker. A name with no value is undefined, while a VALUE followed directly by another marker means the variable is defined but empty. If a name or value contains IAC, it is sent as IAC IAC. If it contains VAR, USERVAR, VALUE or ESC, it is preceded by ESC.
INFO looks like IS but carries changes to variables. It is not used for initial information, and may be sent spontaneously by the WILL side.
There are a few special words: one to ask, one to answer, and one to say something changed. Little markers show where each name and each value starts.
§5Well Known Variables
Six variables are well known: USER (the account name to log into), JOB (a job ID), ACCT (an account ID), PRINTER (the default printer output location, whose format is left undefined), SYSTEMTYPE (the operating system type, matching the FTP SYSTEM command value) and DISPLAY (the X display location, written <host>:<dispnum>[.<screennum>]).
If both DISPLAY and the Telnet X-DISPLAY-LOCATION option arrive and disagree, the most recently received information should be used. For anything else, the USERVAR type lets users send arbitrary name and value pairs. It helps a server tell values derived by host software apart from values the user supplied, though the RFC notes that paranoid implementations will probably distrust both equally.
Some settings have agreed names, like your user name and which screen to draw on. For anything else you can invent your own name.
§6How the Exchange Runs
WILL and DO are used only at the start of the connection, to grant permission. Once they are exchanged, the DO side may request variables. The option may be used at any time, but the exchange usually happens at startup, because many operating systems only pass environment information when a process is created, before the user logs in.
The receiving host does not have to put every variable into the environment. If the terminal type was already learned through the TERMINAL-TYPE option, it can ignore a TERM value. It may also use USER, ACCT and PROJ to choose an account without ever storing them. The suggested approach is to put all unknown information into the user's environment, since that gives the user the most flexibility.
An empty IS reply is legal when no variables are defined. Anyone who supports the option is expected to support all of this specification.
The two computers first agree to talk about settings. Then one asks and the other answers, usually right at the start, and the receiver is free to ignore what it does not need.
- IAC DO ENVIRONHost1 is willing to receive variables.
- IAC WILL ENVIRONHost2 is willing to send them.
- IAC SB ENVIRON SEND VAR "USER" VAR "ACCT" VAR USERVAR IAC SEAsks for USER, ACCT and the default sets.
- IAC SB ENVIRON IS VAR "USER" VALUE "joe" ... IAC SEReturns the variables with their values.
§7Security Concerns
The RFC warns implementors to think about how setting variables interacts with login and authentication. They should analyze carefully which variables are safe to set before the client has logged in.
The example of a bad choice is allowing a variable to be changed in a way that lets an intruder get around or compromise the login or authentication program itself.
If a stranger can change your settings before showing who they are, they might trick the door guard. So be careful about which settings you accept early.