![[Erlang Systems]](min_head.gif)
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.
Starts the auth server.
Stops the auth server.
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.
Returns the value yes if communication with Node is authorized, no if
Node does not exist or communication is not authorized.
Returns yes if Node exists, otherwise no.
Reads cookie from $HOME/.erlang.cookie and sets it. This function is
used by the auth server at start-up.
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.
Another version of the previous function with the arguments in a list which can be given on the host OS command line.
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.