From: Fredrik Tolf Date: Mon, 9 Jul 2007 02:35:29 +0000 (+0200) Subject: Added some protocol command documentation. X-Git-Url: http://git.dolda2000.com/gitweb/?p=doldaconnect.git;a=commitdiff_plain;h=43c0eb2d8744a2f2d3690b723eb226dca33c0c3b Added some protocol command documentation. --- diff --git a/doc/protocol/cmd/cnct.tex b/doc/protocol/cmd/cnct.tex new file mode 100644 index 0000000..0bd80d3 --- /dev/null +++ b/doc/protocol/cmd/cnct.tex @@ -0,0 +1,47 @@ +\syntax{cnct FNET HOSTNAME [(KEY VALUE)...]} + +\begin{reqdesc} + Instructs the daemon to connect to a hub. The \param{FNET} parameter + is the name of the protocol that the hub will be running, and the + \param{HOSTNAME} parameter is the network name of the + hub. Currently, the only supported value for \param{FNET} is + \texttt{dc}, indicating the Direct Connect + protocol. \param{HOSTNAME} may be either an IPv4 address or a + symbolic hostname, followed by a colon and the port number to + connect to. Zero or more key-value pairs may be supplied as well, + setting certain parameters of the protocol operation. Currently + supported keys are: + + \begin{itemize} + \item \texttt{nick}: The nickname to use when speaking to the hub, + instead of the daemon's default nickname. + \item \texttt{password}: The password to supply if the hub asks for + one. + \item \texttt{charset}: For Direct Connect hubs, the character + encoding to use instead of the default CP1252. + \end{itemize} +\end{reqdesc} + +\revision{1} +\perm{fnetctl} + +\begin{responses} + \response{200 ID} + The daemon has created a node for the hub and will be attempting to + connect to it. The \param{ID} parameter is the unique numeric ID for + the new node. + \response{504} + The \param{HOSTNAME} parameter could not be converted to the local + character set on the system running the daemon, so no connection + attempt could be made. + \response{509} + The \param{HOSTNAME} parameter was invalid and could not be parsed + by the daemon. + \response{511} + The daemon does not support the protocol named by the \param{FNET} + parameter. + \response{515} + The daemon administrator has set a quota restricting the maximum + number of connected hubs, and a new connection attempt would violate + that quota. +\end{responses} diff --git a/doc/protocol/cmd/login.tex b/doc/protocol/cmd/login.tex new file mode 100644 index 0000000..8e11d84 --- /dev/null +++ b/doc/protocol/cmd/login.tex @@ -0,0 +1,57 @@ +\syntax{login MECH USERNAME} + +\begin{reqdesc} + Begin an authentication process. The \param{MECH} parameter should + match one of the authentication mechanisms returned by the + \reqref{lsauth} request. The \param{USERNAME} parameter is the name + of the user account to authenticate against. + + Depending on the authentication mechanism, the authentication + process may either succeed immediately, or require further + information, which should be passed in subsequent \reqref{pass} + requests. +\end{reqdesc} + +\revision{1} +\noperm + +\begin{responses} + \response{200} + The authentication succeeded, and the communication channel is now + considered logged in by the daemon. + \response{300 DATA} + The authentication process needs more data. The \param{DATA} + parameter contains data specific to the mechanism being carried + out. The client should process it appropriately and send the + response data in a \reqref{pass} request. + \response{301 PROMPT} + The authentication process needs data from the user, + interactively. The \param{PROMPT} parameter should be presented to + the user, and a string of text should be requested from the user + without echoing it on the screen (probably a password prompt). + \response{302 PROMPT} + Like 301, but the data should be echoed on the screen. + \response{303 INFO} + The authentication mechanism wishes to present data to the user. The + \param{INFO} parameter is a string that should be displayed to the + user. + \response{304 INFO} + Like 303, but \param{INFO} should be considered an error. + \response{503} + This communication channel is already logged in, and therefore + cannot start an authentication process. + \response{504} + The \param{USERNAME} parameter was invalid, as it could not be + converted to the local character set of the system running the + daemon. + \response{505} + A system error of some kind occurred that prevented authentication + from proceeding. The daemon administrator should consult the logs to + find the cause of the error. + \response{506} + The authentication failed. Probable reasons include incorrect + passwords, expired Kerberos tickets, etc. + \response{508} + The mechanism specified in the \param{MECH} parameter is not + supported by the daemon. +\end{responses} diff --git a/doc/protocol/cmd/lsauth.tex b/doc/protocol/cmd/lsauth.tex new file mode 100644 index 0000000..ba5f697 --- /dev/null +++ b/doc/protocol/cmd/lsauth.tex @@ -0,0 +1,20 @@ +\syntax{lsauth} + +\begin{reqdesc} + Return the available methods of authentication. +\end{reqdesc} + +\revision{1} +\noperm + +\begin{responses} + \response{200 MECH} + One of these lines is returned for every supported authentication + mechanism. The \param{MECH} parameter is the name of one supported + authentication mechanism. + \response{201} + A 201 response indicates that the daemon supports no authentication + mechanism. Since it is impossible to do anything meaningfully + without authenticating, this should never happen, but it could still + happen e.g. in the case of a configuration error. +\end{responses} diff --git a/doc/protocol/cmd/pass.tex b/doc/protocol/cmd/pass.tex new file mode 100644 index 0000000..95d1784 --- /dev/null +++ b/doc/protocol/cmd/pass.tex @@ -0,0 +1,18 @@ +\syntax{pass DATA} + +\begin{reqdesc} + Pass additional data to the current authentication process. The + \param{DATA} paremeter is the data to be passed, and it is specific + to each authentication mechanism. +\end{reqdesc} + +\revision{1} +\noperm + +\begin{responses} + \response{507} + No authentication process is currently active, so no data was + expected. +\end{responses} +Otherwise, all responses to the \reqref{login} command are valid for +the \texttt{pass} command as well, except the 503 error. diff --git a/doc/protocol/cmd/quit.tex b/doc/protocol/cmd/quit.tex new file mode 100644 index 0000000..fe48f51 --- /dev/null +++ b/doc/protocol/cmd/quit.tex @@ -0,0 +1,17 @@ +\syntax{quit} + +\begin{reqdesc} +Instruct the daemon to close the connection to the client. This +request is not actually necessary, as it is just fine for the client +to close the connection from its side instead, but it is at least +convenient when talking to the daemon with a program such as +\texttt{telnet}. +\end{reqdesc} + +\revision{1} +\noperm + +\begin{responses} + \response{200} + The daemon will close the connection at its earliest convenience. +\end{responses}