

  Section     Title

      1       Introduction
      2       Compiling dipcd
      3       Installing dipcd
      4       Running dipcd
      5       dipcd command line arguments  
      6       DIPC Configuration file: /etc/dipc.conf
      7       The /etc/dipc.allow file



1.0) Introduction
 dipcd is the user space part of DIPC, running with root privileges. It 
does all the decision makings, manages the requests and transfers data to 
requesting machines. It should be running on all the machines in the cluster.

 dipcd uses ordinary means to access IPC structures (e.g. using a msgsnd()
to send a message), but is, in some ways, treated differently by the kernel,
enabling it to do things that ordinary user processes can not do. 

 Some dipcd processes set up a UNIX domain socket (back door), and allow
other processes to see and change information important for DIPC's
operations. Programs in the tools directory of DIPC package use this
feature.


2.0) Compiling dipcd
 The following C files are needed to compile dipcd: referee.c, back_end.c,
employer.c, worker.c, shm_man.c, front_end.c and support.c. The following
header files are also needed: dipcd.h and funcs.h. A make file is provided. 
Just type make to compile and link dipcd.


3.0) Installing dipcd
 A good place to put dipcd seems to be /usr/sbin.


4.0) Running dipcd
 dipcd should be activated when you boot the machine. Running dipcd
after a program has used System V IPC mechanisms will probably lead to
problems. The file rc.local in /etc/rc.d file seems to be a good place to
add a line to cause automatic execution of dipcd. It outputs messages to the 
standard error file (stderr), so you may like to redirect it. You could use 
a command line like this: /usr/sbin/dipcd 2>/tmp/dipcd_mess


5.0) dipcd command line arguments
 the following arguments are recognized by dipcd:
  
 *) '-t' disables the time-out mechanism of dipcd, meaning that dipcd will not
 use any time-out to detect possible problems. See the theory file for more
 information about time outs. 

 *) '-u' signals dipcd to use UDP/IP. The default is TCP/IP. All the
 computers in the same cluster should use the same networking protocol.

 *) '-n' causes dipcd to convert the outgoing data to network byte order.
 This is of use in heterogeneous systems.

 *) '-s' makes DIPC more secure by causing the front_end process not to respond 
 to any connection from a computer who's address is not in the /etc/dipc.allow 
 file.

  NOTE: Every computer that uses this option SHOULD also have the 
 /etc/dipc.allow file. Also, using symbolic addresses may cause some delays
 in dipcd's startup, as it tries to resolve the symbolic names right after
 it has been executed.

 *) '-v' makes the dipcd program verbose: dipcd will display messages as it 
 does its work. This is mainly of interest for debugging. It could also be used 
 by graphical simulators to trace the system. Each message starts like this: 
 [<task_no.>@<file_name>:<line_no.>]{<hours>:<minutes>:<seconds>:<100th sec>} 
 
  The time is measured relative to the start of dipcd. This is followed by the 
 actual message.
 
 *) '-c' tells dipcd to log information related to the data conversion
 routines. The conversions are needed in heterogeneous environments.

 *) '-d' logs the converted information. Some of these information are also
 logged by the '-v' argument.

 These options could be given either one at a time (-v -s), or all in the same
argument (-vs).

  NOTE: dipcd outputs its logs to the standard output, so you may want to
 redirect it to a file. Alos, using -v, -c or -d can lead to the generation 
 of an enormous amount of data in a short time.


6.0) DIPC Configuration file: /etc/dipc.conf
 dipcd reads this file on startup to get necessary information. It is
located in /etc directory. The general format of the entries in this file 
is <var> = <value>. '#' is used as start of comments. The two entries that
must be present are the IP address of the machine you want to run dipc
on, and also the IP address of the referee machine (see the Theory file).

 NOTE: Some computers may acquire an IP address dynamically. Others could 
boot from a server, thus more than one computer would see a single 
/etc/dipc.conf. in order to enable DIPC to work in these systems properly, 
the administrator can instruct dipcd to query the address of the computer 
after it has started running. dipcd uses the name of the computer as set by 
the 'hostname' command, to find the needed IP address. The referee's address
should be given in /etc/dipc.conf if it is to be part of the cluster.

 Two other entries determine the shared memory transfer mode of DIPC and
control whether DIPC should send signals to processes that have become a 
reader or writer of parts of a shared memory or not. 

 Other entries determine the time-outs used by various parts of dipcd.
Positive time-out values indicate that you want the time-out to be used. A
zero or negative value means that you don't want dipcd to use the time-out
mechanism for that particular action. So you can control individual time-outs. 
As mentioned before, you can use the -t command line argument to disable the
whole time-out mechanism, regardless of individual time-out values. The
exception here is the shm_hold_timeout, which is always used. These entries
can be omitted, in which case default values will be used.

 Here are the recognized entries:

6.1) this_machine : IP address of this machine, in w.x.y.z or in symbolic 
notation. If symbolic, dipcd will try to resolve the address on start-up.

NOTE: Some computers may acquire an IP address dynamically. Others could 
boot from a server, thus more than one computer would see a single 
/etc/dipc.conf. in order to enable DIPC to work in these systems properly, 
the administrator can instruct dipcd to query the address of the computer 
after it has started running. this is done by using 'dipc_auto_find' as the 
value of this_machine. In this case dipcd uses the name of the computer as 
set by the 'hostname' command, to find the needed IP address. 

6.2) referee : IP address of the referee to whom this machine will refer,
in w.x.y.z or in symbolic notation. If symbolic, dipcd will try to resolve
the address on start-up. You could set 'referee' to the same valid IP address 
as 'this_machine', but don't use 'dipc_auto_find' for the referee. 

6.3) transfer_mode : If equal to 'segment', then DIPC will use a segment as
the unit of shared memory management and transfer. 'Page' forces DIPC to
use pages. The page size is determined by dipc_page_size entry in the
dipc.conf file. 

6.4) dipc_page_size : If transfer_mode is 'Page', then this value is used
as the size of the virtual page size managed and transfered over the network
by DIPC, Otherwise it is not used. This value can be a multiple of the 
system's virtual memory page size. 

6.5) inhibit_shm_signal : If equal to 'yes', DIPC will not send a signal to
readers or writers of a shared memory. 'no' causes the signals to be sent.

6.6) employer_referee_timeout : The amount of time in seconds that the
employer will wait for a reply from referee. This is the time a referee has
to answer to requests. It is used whenever an employer wants to contact the
referee. These include, searching for a IPC structure, and removing or
deleting an IPC structure.

6.7) employer_shm_timeout : The amount of time in seconds that the employer
will wait for a reply from a shared memory manager. This is used when the
employer wants to handle a shared memory read or write. If the number of
processes accessing a shared memory simultaneously is large, then this time
should be increased.

6.8) employer_worker_timeout' : The amount of time in seconds that the
employer will wait for a reply from a worker. Its use includes the time
allowed for remote procedure calls. So for example a wait for a semaphore
(via a semop() function) should return within this time. This is different
from the normal IPC case, where for example a semop() could not return for
a very long time. In DIPC, as far as the employer is concerned, there is no
way to distinguish between a system call that is not returning fast, and
some problem in the remote machine or the network. This time out value should
be adjusted for different applications. Remember that the above time-out
applies only to requests from other machines, not the one on which the IPC
structure was created. Processes on this machine can wait indefinitely.

6.9) shm_ak_timeout : When a computer requests the contents of a shared
memory, the responsible shared memory manager will directly or indirectly
send it the contents, and then waits for an acknowledgment. This value
gives the amount of time in seconds that the shared memory manager will
wait for it.

6.10) referee_timeout : After the referee sends the information about an IPC
structure to a requesting machine, it will wait for this amount of time to
receive a reply, to find out if the machine created an structure with the
corresponding key or not.
 
6.11) shm_hold_timeout : This gives the time quantum in split seconds, for
the shm_man. It is used in scheduling machines who request to access the
shared memory, and determines the minimum time that a computer can access
the shared memory before it is given to someone else. It is not possible to 
disable this timeout in any way.


7.0) The /etc/dipc.allow file

 This file lists the address of computers which are allowed to take part in
a DIPC cluster. The computers named in the file don't have to actually be in 
the cluster, but they can be, if they ever want to.

 These addresses can be in the number-dot (e.g 194.165.8.3) or symbolic (e.g. 
sun.iust.ac.ir) formats. There should be one address per line. The '#' symbol 
can be used as the start of a comment.

 This file should also contain the address of the referee computer itself.

 The /etc/dipc.allow file SHOULD be present in the referee computer. Its
existence in non-referee computers is needed only when the '-s' option is
used. See the theory file (security section) for more information.

 When the referee process encounters a SIGHUP signal, it will reread the
contents of this file. This could be used to change the set of trusted
computers on the fly.

