auth

auth(3)                    ERLANG MODULE DEFINITION                    auth(3)



MODULE
       auth -  The Erlang Network Authentication Server

DESCRIPTION
       Authentication determines which nodes are allowed to communicate with
       each other. In a network of different Erlang nodes, it is built into
       the system at the lowest possible level. Each node has its Magic
       Cookie, which is an Erlang atom.

       Whenever a message is transferred from one node to another, it is
       accompanied by the Magic Cookie of the receiving node. For example, a
       message transferred from node A to node B is accompanied by what node A
       believes to be theMagic Cookie of node B.

       When the message arrives at node B, the runtime system immediately
       checks that the accompanying cookie is the right one. If it is, the
       message is passed on in the normal way. If it is not, the message is
       transformed into a badcookie message, which is sent to the system
       process net_kernel. By default, the net_kernel process passes the
       message to the registered process auth, which is then responsible for
       taking the appropriate action for the unauthorized message. In the
       standard system, the default action is to shut down connection to that
       node.

       At start-up, the first action of the standard auth server is to read a
       file named $HOME/erlang.cookie. An atom is created from the contents of
       this file and the cookie of the node is set to this atom with the use
       of erlang:set_cookie(node(), CookieAtom).

       If the file does not exist, it is created. The UNIX permissions mode of
       the file is set to octal 400 (read-only by owner) and filled with a
       random string. For this reason, the same user, or group of users with
       identical cookie files, can have Erlang nodes which can communicate
       freely and without interference from the Magic Cookie system. Users who
       want to run nodes on separate file systems must be certain that their
       cookie files are identical on the different file systems.

       Initially, each node has a random atom assigned as its magic cookie.
       Once the procedure described above has been concluded, the cookie is
       set to the contents of the $HOME/erlang.cookie file.

       To communicate with another node, the magic cookie of that node must be
       known. The BIF erlang:set_cookie(Node, Cookie) sets the cookie for Node
       to Cookie. From then on, all messages will be accompanied by the cookie
       Cookie. If the cookie is not correct when messages arrive at Node, they
       are sent to the auth server at Node. The call erlang:set_cookie(node(),
       CookieAtom) will set the current cookie to CookieAtom. It will,
       however, also set the cookie of all other unknown nodes to CookieAtom.
       In the case of the default auth server, this is the first thing done
       when the system starts. The default then, is to assume that all nodes
       which communicate have the same cookie. In the case of a single user on
       a single file system, this is indeed true and no further action is
       required. The original cookie can also be fetched by the BIF
       erlang:get_cookie().

       If nodes which communicate do not have the same cookie, they can be set
       explicitly on each node with the aid of erlang:set_cookie(Node,
       Cookie). All messages sent to the node Node will then be accompanied by
       the cookie Cookie. Distributed systems with multiple User IDs can be
       handled in this way.

       Initially, the system cookie is set to a random atom, and the (assumed)
       cookie of all other nodes is initially set to the atom nocookie. Thus,
       an Erlang node is completely unprotected when erlang:set_cookie(node(),
       nocookie) is run. Sometimes, this may be appropriate for systems which
       are not normally networked, and it can also be appropriate for
       maintenance purposes.

       In the standard system, the default when two nodes are connected is to
       immediately connect all other involved nodes as well. This way, there
       is always a fully connected network. If there are nodes with different
       cookies, this method might be inappropriate and the host OS command
       line option -connect_all false must be issued to the Erlang runtime
       system. See global(3).

       This module uses the two BIFs erlang:get_cookie() which returns the
       magic cookie of the local node, and erlang:set_cookie(Node, Cookie)
       which sets the magic cookie of Node to Cookie. If Node is the user's
       node, the cookie of all other unknown nodes are also set to Cookie by
       this BIF.


EXPORTS
       start()

              Starts the auth server.

       stop()

              Stops the auth server.

       open(Name)

              This function opens up the server with the name Name. If, for
              example, node N is run with the cookie C, it is impossible for
              other nodes with other cookies to communicate with node N. The
              call open/1 opens the server with the registered name Name so it
              can be accessed by any other node, irrespective of cookie. The
              call must be executed on both nodes to have any effect. All
              messages to the server must have the form Name ! Msg and all
              replies from the server {Name, Reply}, or {Name, Node, Reply}.
              With this feature, it is possible to perform specific tasks on
              publicly announced Erlang network servers.

       is_auth(Node)

              Returns the value yes if communication with Node is authorized,
              no if Node does not exist or communication is not authorized.

       exists(Node)

              Returns yes if Node exists, otherwise no.

       cookie()

              Reads cookie from $HOME/.erlang.cookie and sets it. This
              function is used by the auth server at start-up.

       node_cookie(Node, Cookie)

              If the cookie of Node is known to the user as Cookie but the
              user's cookie is not known at Node, this function informs Node
              of the identity of the user's cookie.

       node_cookie([Node, Cookie])

              Another version of the previous function with the arguments in a
              list which can be given on the host OS command line.

       cookie([Cookie])

              Equivalent to erlang:set_cookie(node(), Cookie), but with the
              argument in a list so it can be given on the host OS command
              line.

AUTHOR
        Claes Wikstrom - support@erlang.ericsson.se



Ericsson Utvecklings AB          kernel  2.7.2                         auth(3)