139 lines
5.5 KiB
TeX
139 lines
5.5 KiB
TeX
\chapter{Reading netrc-files}\label{cha:netrc}
|
|
%
|
|
\begin{description}
|
|
\item[Used files:] netrc.scm
|
|
\item[Name of the package:] netrc
|
|
\end{description}
|
|
%
|
|
\section{Overview}
|
|
This module provides procedures to parse authentication information
|
|
contained in \ex{~/.netrc}.
|
|
|
|
On Unix systems the \ex{~/.netrc} file (in the user's home directory)
|
|
may contain information allowing automatic login to remote hosts. The
|
|
format of the file is defined in the \ex{ftp}(1) manual page. Example
|
|
lines are
|
|
\begin{alltt}
|
|
machine ondine.cict.fr login marsden password secret
|
|
default login anonymous password user@site%
|
|
\end{alltt}
|
|
|
|
The \ex{~/.netrc} file should be protected by appropriate permissions, and
|
|
(like \ex{/usr/bin/ftp}) this library will refuse to read the file if it is
|
|
badly protected. (unlike \ex{ftp} this library will always refuse
|
|
to read the file -- \ex{ftp} refuses it only if the password is
|
|
given for a non-default account). Appropriate permissions are set if
|
|
only the user has permissions on the file.
|
|
|
|
Note following restrictions and differences:
|
|
\begin{itemize}
|
|
\item The macdef statement (defining macros) is not supported.
|
|
\item The settings for one machine must be on a single line.
|
|
\item The is no error proof while reading the file.
|
|
\item Default need not be the last line of the netrc-file.
|
|
\end{itemize}
|
|
|
|
|
|
|
|
\section{Entry points}
|
|
|
|
What you probably want, is to read out the default netrc-file. Do the
|
|
following:
|
|
\begin{alltt}
|
|
(let ((netrc-record (netrc:parse)))
|
|
(netrc:lookup netrc-record "name of the machine"))
|
|
\end{alltt}
|
|
|
|
and you will receive three values: \semvar{login-name},
|
|
\semvar{password} and \semvar{account-name}. If you only want the
|
|
login name or the password, use \ex{netrc:\ob{}lookup\=login} or
|
|
\ex{netrc:\ob{}lookup\=password}, resp.
|
|
|
|
You will get either the login / password for the specified machine, or
|
|
a default login / password if the machine is unknown.
|
|
|
|
|
|
\begin{defundesc}{user-mail-address}{}{string}
|
|
Calculate the user's email address, as per the Emacs function of the
|
|
same name. Will take into account the environment variable
|
|
\ex{REPLYTO}, if set. Otherwise the mail-address will look like
|
|
\ex{user@\ob{}hostname}.
|
|
\end{defundesc}
|
|
|
|
\defun{netrc:parse} {[filename] [fallback-password] [fallback-login]} {netrc-record}
|
|
\begin{defundescx}{netrc:try-parse} {filename fallback-password
|
|
fallback-login} {netrc-record}
|
|
|
|
\ex{netrc:parse} parses the netrc file and returns a \ex{netrc}
|
|
record, containing all necessary information for the following
|
|
procedures.
|
|
|
|
\semvar{filename} defaults to ``~/.netrc'',
|
|
\semvar{fallback-password} defaults to the result of the call to
|
|
\ex{user\=mail\=address} and \semvar{fallback-login} defaults to
|
|
``anonymous''. If the netrc file does not provide a default password
|
|
or a default login (stated by the ``default'' statement),
|
|
\semvar{fallback-password} and \semvar{fallback-login} will be used
|
|
as default password or login, respectively (thus,
|
|
\ex{user\=mail\=address} is only called if the netrc file does not
|
|
contain a default specification). If the netrc file does not exist,
|
|
a netrc-record filled with default values is returned. If the netrc
|
|
file does not have the correct permissions, a message is printed to
|
|
the current error port and a netrc-record filled with default values
|
|
is returned.
|
|
|
|
\ex{netrc:try-parse} does the same as \ex{netrc:\ob{}parse}, except
|
|
of the following: if there is no file called \semvar{filename}, the
|
|
according error will be raised and if the specified file does not
|
|
have the correct permissions set, a \ex{netrc\=refuse\=warning} will
|
|
be signalled. So, if you don't like the error handling and behavior
|
|
of \ex{netrc:\ob{}parse}, use \ex{netrc:\ob{}try\=parse} and catch
|
|
the signalled conditions. Note, that \ex{netrc:\ob{}parse} resolves
|
|
\semvar{filename} for you, \ex{netrc:\ob{}try-parse} does not -- you
|
|
have to do it on your own.
|
|
\end{defundescx}
|
|
|
|
\defun{netrc:lookup}{netrc-record machine [default?]} {string string string}
|
|
\defunx{netrc:lookup-password}{netrc-record machine [default?]}{string}
|
|
\defunx{netrc:lookup-login}{netrc-record machine [default?]}{string}
|
|
\begin{desc}
|
|
Return the login, password and / or account information for
|
|
\semvar{machine} specified by \semvar{netrc-record}, respectively.
|
|
If \semvar{default?} is \sharpt, default values are returned if no
|
|
such \semvar{machine} is specified in the \semvar{netrc-record}.
|
|
Otherwise [\sharpf\ \sharpf\ \sharpf] or \sharpf\ is returned,
|
|
respectively.
|
|
\end{desc}
|
|
|
|
\defun{netrc:default-login}{netrc-record}{string}
|
|
\begin{defundescx}{netrc:default-password}{netrc-record}{string}
|
|
Return the default values for the login or the password, respectively,
|
|
specified by \semvar{netrc-record}. If the netrc file did not
|
|
specify a default login, ``anonymous'' is returned by
|
|
\ex{netrc:\ob{}default\=login}. If the netrc file did not specify a
|
|
default password, the result of the call to \ex{user\=mail\=address}
|
|
is returned by \ex{netrc:\ob{}default\=password}.
|
|
\end{defundescx}
|
|
|
|
\section{Related work}
|
|
\begin{itemize}
|
|
\item Graham Barr has written a similar library for Perl, called
|
|
\ex{Netrc.pm}.
|
|
\item \ex{ange-ftp.el} (transparent remote file access for Emacs)
|
|
parses the user's netrc file.
|
|
\end{itemize}
|
|
|
|
\section{Desirable things}
|
|
\begin{itemize}
|
|
\item Remove restrictions (as stated in `\emph{Overview}') and behave like
|
|
\ex{/usr/\ob{}bin/\ob{}ftp} behaves
|
|
\item perhaps: adding case-insensitivity (for host names)
|
|
\item perhaps: better record-disclosers for netrc-entry- and
|
|
netrc-records
|
|
\end{itemize}
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: "man"
|
|
%%% End:
|