<CHAPTER ID="Admin">
<TITLE>Administrating openMosix</TITLE>
<SECT1><TITLE>Basic Administration</TITLE>

<PARA>openMosix provides the advantage of process migration to HPC-applications. 
The administrator can configure and tune the openMosix-cluster by using 
the openMosix-user-space-tools
or the /proc/hpc interface which will be now described in detail.
</PARA>
<para>
Up till  openMosix version 2.4.16 the /proc interface was  named 
/proc/mosix !
Until openMosix version 2.4.17 it was named /proc/hpc.

</para>

</SECT1><SECT1><TITLE>Configuration</TITLE>
<PARA>
The values in the flat files in the /proc/hpc/admin directory presenting 
the current configuration of
the cluster. Also the administrator can write its own values into these 
files to change the configuration 
during runtime, e.g.
</para>
<table frame=all><title>Changing /proc/hpc parameters</title>
<tgroup cols=2 align=left>
<tbody>
<row><entry>
echo 1 > /proc/hpc/admin/block</entry><entry>blocks the arrival of remote processes</entry>
</row>
<row>
<entry>
echo 1 > /proc/hpc/admin/bring</entry><entry>bring all migrated processes home</entry>
</row>
</tbody></tgroup>
</table>
<para>
...
</para>

<table frame=all><title>/proc/hpc/admin/</title>
<tgroup cols=3 align=left>
<tbody>
<row><entry>
(binary files) </entry><entry>         config          			</entry><entry>
					the main configuration file (written by the setpe util)</entry></row>

<row><entry>
(flat files)</entry><entry>            block </entry><entry>          allow/forbid arrival of remote processes</entry></row>

<row><entry></entry><entry>                        bring  </entry><entry>         bring home all migrated processes
</entry></row>
<row><entry></entry><entry>  
                        dfsalinks </entry><entry>      list of current symbolic dfsa-links
</entry></row>

<row><entry></entry><entry>  
                        expel  </entry><entry>          sending guest processes home
</entry></row>

<row><entry></entry><entry>  
                        gateways     </entry><entry>    maximum number of gateways
</entry></row>

<row><entry></entry><entry>  
                        lstay      </entry><entry>      local processes should stay

</entry></row>
<row><entry></entry><entry>  

                        mospe      </entry><entry>      contains the openMosix node id
</entry></row>
<row><entry></entry><entry>  
                        nomfs    </entry><entry>        disables/enables MFS
</entry></row>
<row><entry></entry><entry>  
                        overheads    </entry><entry>    for tuning
</entry></row>
<row><entry></entry><entry>  
                        quiet  </entry><entry>          stop collecting load-load-balancing informations
</entry></row>
<row><entry></entry><entry>  
                        decay-interval  </entry><entry>  interval for collecting informations about load-balancing
</entry></row>
<row><entry></entry><entry>  
                        slow-decay      </entry><entry>  default 975
</entry></row>
<row><entry></entry><entry> 
                        fast-decay   </entry><entry>     default 926
</entry></row>
<row><entry></entry><entry>  
                        speed  </entry><entry>          speed relative to PIII/1GHz)
</entry></row>
<row><entry></entry><entry>  
                        stay      </entry><entry>       enables/disables automatic process migration
</entry></row>
</tbody></tgroup></table>

<table frame=all><title>Writing a 1 to the following files /proc/hpc/decay/</title>
<tgroup cols=2 align=left>
<tbody>
<row><entry>

                        clear </entry><entry>          clears the decay statistics
</entry></row>
<row><entry>

                        cpujob      </entry><entry>    tells openMosix that the process is cpu-bound
</entry></row>
<row><entry>
                        iojob    </entry><entry>       tells openMosix that the process is io-bound
</entry></row>
<row><entry>

                        slow    </entry><entry>        tells openMosix to decay its statistics slow
</entry></row>
<row><entry>
                        fast     </entry><entry>       tells openMosix to decay its statistics fast
</entry></row>
</tbody></tgroup></table>



<table frame=all><TITLE>Informations about the other nodes</TITLE>
<tgroup cols=2 align=left>
<tbody>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/CPUs </entry><entry>            how many CPU's the node has
</entry></row>
<row><entry>

/proc/hpc/nodes/[openMosix_ID]/load  </entry><entry>            the openMosix load of this node
</entry></row>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/mem         </entry><entry>      available memory as openMosix believes
</entry></row>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/rmem  </entry><entry>            available memory as Linux believes
</entry></row>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/speed    </entry><entry>         speed of the node relative to PIII/1GHz
</entry></row>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/status       </entry><entry>     status of the node
</entry></row>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/tmem  </entry><entry>            available memory
</entry></row>
<row><entry>
/proc/hpc/nodes/[openMosix_ID]/util        </entry><entry>      utilization of the node
</entry></row>

</tbody>
</tgroup></table>


<table frame=all><title>
Additional Informations about local processes
</title>

<tgroup cols=2 align=left>
<tbody>

<row><entry>

/proc/[PID]/cantmove         </entry><entry>           reason why a process cannot be migrated
</entry></row>
<row><entry>
/proc/[PID]/goto                      </entry><entry>  to which node the process should migrate
</entry></row>
<row><entry>
/proc/[PID]/lock                        </entry><entry>if a process is locked to its home node
</entry></row>
<row><entry>
/proc/[PID]/nmigs                       </entry><entry>how many times the process migrated
</entry></row>
<row><entry>
/proc/[PID]/where                       </entry><entry>where the process is currently being computed
</entry></row>
<row><entry>
/proc/[PID]/migrate                     </entry><entry>same as goto remote processes
</entry></row>
<row><entry>
/proc/hpc/remote/from                   </entry><entry>the home node of the process
</entry></row>
<row><entry>
/proc/hpc/remote/identity               </entry><entry>additional informations about the process
</entry></row>
<row><entry>
/proc/hpc/remote/statm                  </entry><entry>memory statistic of the process
</entry></row>
<row><entry>
/proc/hpc/remote/stats                  </entry><entry>cpu statistics of the process

</entry></row>
</tbody></tgroup></table>

</SECT1>

<SECT1><TITLE>the userspace-tools</TITLE>
<PARA>

These following tools are providing easy administration to openMosix 
clusters.

<PROGRAMLISTING>
migrate -send a migrate request to a process
                syntax: 
                        migrate [PID] [openMosix_ID]
</PROGRAMLISTING>
<PROGRAMLISTING>


mon             -is a ncurses-based terminal monitor
                 several informations about the current status are displayed in bar-charts
</PROGRAMLISTING>
<PROGRAMLISTING>

mosctl          -is the openMosix main configuration utility
                syntax:
                        mosctl  [stay|nostay]
                                [lstay|nolstay]
                                [block|noblock]
                                [quiet|noquiet]
                                [nomfs|mfs]
                                [expel|bring]
                                [gettune|getyard|getdecay]

                        mosctl  whois   [openMosix_ID|IP-address|hostname]

                        mosctl  [getload|getspeed|status|isup|getmem|getfree|getutil]   [openMosix_ID]

                        mosctl  setyard [Processor-Type|openMosix_ID||this]

                        mosctl  setspeed        interger-value

                        mosctl  setdecay interval       [slow fast]
</PROGRAMLISTING>

<table frame=all><title>more detailed</title>
<tgroup cols=2 align=left>
<tbody><row><entry>


stay            </entry><entry>no automatic process migration
</entry></row>
<row><entry>

nostay          </entry><entry>automatic process migration (default)
</entry></row>
<row><entry>
lstay           </entry><entry>local processes should stay
</entry></row>
<row><entry>
nolstay         </entry><entry>local processes could migrate
</entry></row>
<row><entry>
block           </entry><entry>block arriving of guest processes
</entry></row>
<row><entry>
noblock         </entry><entry>allow arriving of guest processes
</entry></row>
<row><entry>
quiet           </entry><entry>disable gathering of load-balancing informations
</entry></row>
<row><entry>
noquiet         </entry><entry>enable gathering of load-balancing informations
</entry></row>
<row><entry>
nomfs           </entry><entry>disables MFS
</entry></row>
<row><entry>
mfs             </entry><entry>enables MFS
</entry></row>
<row><entry>
expel           </entry><entry>send away guest processes
</entry></row>
<row><entry>
bring           </entry><entry>bring all migrated processes home
</entry></row>
<row><entry>
gettune         </entry><entry>shows the current overhead parameter
</entry></row>
<row><entry>
getyard         </entry><entry>shows the current used Yardstick
</entry></row>
<row><entry>
getdecay        </entry><entry>shows the current decay parameter
</entry></row>
<row><entry>
whois           </entry><entry>resolves openMosix-ID, ip-addresses and hostnames of the cluster
</entry></row>
<row><entry>
getload         </entry><entry>display the (openMosix-) load
</entry></row>
<row><entry>
getspeed        </entry><entry>shows the (openMosix-) speed
</entry></row>
<row><entry>
status          </entry><entry>displays the current status and configuration
</entry></row>
<row><entry>
isup            </entry><entry>is a node up or down (openMosix kind of ping)
</entry></row>
<row><entry>
getmem          </entry><entry>shows logical free memory
</entry></row>
<row><entry>
getfree         </entry><entry>shows physical free mem
</entry></row>
<row><entry>
getutil         </entry><entry>display utilization
</entry></row>
<row><entry>
setyard         </entry><entry>sets a new Yardstick-value
</entry></row>
<row><entry>
setspeed        </entry><entry>sets a new (openMosix-) speed value
</entry></row>
<row><entry>
setdecay        </entry><entry>sets a new decay-interval
</entry></row>
</tbody></tgroup></table>



<PROGRAMLISTING>

mosrun          -run a special configured command on a chosen node
                syntax:
                        mosrun  [-h|openMosix_ID| list_of_openMosix_IDs] command [arguments]
</PROGRAMLISTING>
</PARA><PARA>
The mosrun command can be executed with several more commandline options. 
To ease this up there are several preconfigured run-scripts for executing 
jobs with a special (openMosix) configuration.
</PARA>

<table frame=all><title>extra options for mosrun</title>
<tgroup cols=2 align=left>
<tbody><row><entry>
nomig           </entry><entry>runs a command which process(es) won't migrate
</entry></row>
<row><entry>
runhome         </entry><entry>executes a command locked to its home node
</entry></row>
<row><entry>
runon           </entry><entry>runs a command which will be directly migrated and locked to a node
</entry></row>
<row><entry>
cpujob  	</entry><entry>tells the openMosix cluster that this is a cpu-bound process
</entry></row>
<row><entry>
iojob           </entry><entry>tells the openMosix cluster that this is a io-bound process
</entry></row>
<row><entry>
nodecay         </entry><entry>executes a command and tells the cluster not to refresh the load-balancing statistics
</entry></row>
<row><entry>
slowdecay       </entry><entry>executes a command with a slow decay interval for collecting load-balancing statistics
</entry></row>
<row><entry>
fastdecay       </entry><entry>executes a command with a fast decay interval for collecting load-balancing statistics
</entry></row>
</tbody></tgroup></table>

<PROGRAMLISTING>

setpe           -manual node configuration utility
                syntax:
                        setpe   -w -f   [hpc_map]
                        setpe   -r [-f  [hpc_map]]
                        setpe   -off

-w reads the openMosix configuration from a file (typically /etc/hpc.map)
-r writes the current openMosix configuration to a file (typically /etc/hpc.map)
-off turns the current openMosix configuration off
</PROGRAMLISTING>
<PROGRAMLISTING>

tune            openMosix calibration and optimizations utility.
                (for further informations review the tune-man page)

</PROGRAMLISTING>


<PARA>
Additional to the /proc interface and the commandline-openMosix utilities 
(which are using the 
/proc interface) there is a patched "ps" and "top" available (they are 
called "mps" and "mtop")
which displays also the openMosix-node ID on a column. This is useful for 
finding out where a
specific process is currently being computed.
</PARA>
<!-- 
<PARA>
The administrator can have a overview about the current status of the 
cluster and its nodes with
the "Mosix Cluster Information Tool PHP" which can be found at 
<ulink url="http://wijnkist.warande.uu.nl/mosix/"><citetitle> http://wijnkist.warande.uu.nl/mosix/
</citetitle></ulink>

 .
(the path to the NODESDIR has to be adjusted to 
$NODESDIR="/proc/hpc/nodes/")
</PARA> -->
<PARA>
This actually summarised the command line tools, but have a look at 
openMosixview which is 
a 

GUI for the most common 
administration tasks, and which ill be discussed in a future chapter.
</PARA>
</SECT1>

<sect1><title>Cluster Mask</title>
<para>
(by Moshe Bar)
</para><para>
Several people have asked for a feature in openMosix which allows to 
specifiy to which nodes a given process and it's children can migrate 
and to which nodes it cannot.
</para>
<para>
Simone Ettore has just committed a new patch to the CVS which allows 
you to do just that.
</para>
<para>
Here is how it works:

<itemizedlist><listitem>
<para>
/proc/[pid]/migfilter enable/disable the capability of filter migration.
</para>
</listitem>
<listitem>
<para>
/proc/[pid]/mignodes is a bit-list of nodes. The bit position of a node 
is calculated as 2^(PE-1). PE is node number.
</para></listitem>
<listitem><para>
/proc/[pid]/migpolicy is the policy of the filtering:
0=DENY: the process can migrate in all nodes except when the relative
bit on mignodes is 1
1=ALLOW: the process can migrate in all nodes where the relative bit on
mignodes is 1
</para>
</listitem>
</itemizedlist>
</para>
<para>

We are shortly going to release also a simple user-land tool to set the 
node mask, but I would like you guys to give it a try asap before we 
release it as openMosix 2.4.20-3.
</para>


</sect1>

</CHAPTER>


