<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{pHostInfo: Detecting and Sharing Host Info}
\vspace{0.1in}
\labdate{June 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PHostInfo}
\wikidoc{bugz=phostInfo}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overview}
%===================================================================
\label{sec_phostinfo}
%\index{pHostInfo}

The \app{pHostInfo} application is a tool with a simple objective -
determine the IP address of the machine on which it is running and
post it to the MOOSDB. Although this information is available in a
number of ways to a user at the keyboard, it may not be readily
available for reasoning about within a MOOS community. Often, from an
application's perspective, the host name is simply known and
configured as {\em localhost}. This is fine for most purposes, but in
situations where a user is on a machine where the IP address changes
frequently, and the user is launching MOOS processes that talk to
other machines, it may be very convenient to auto-determine the
prevailing IP address and publish it to the MOOSDB. The typical usage
scenario for \app{pHostInfo} is shown in Figure
\ref{fig_phi_topology}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/phi_topology.png}
  \caption{{\bf Typical pHostInfo Topology:} A shoreside or topside
    community is receiving information from several deployed vehicles,
    in the form of node reports. The node reports contain time-stamped
    updated vehicle positions, from which the speed and distance
    measurements are derived and posted to the shoreside MOOSDB.}
\label{fig_phi_topology}
\end{figure}

There are two scenarios where this is currently envisioned to be
useful.  The first is when the fielded vehicles are on the network
with their IP addresses set via DHCP. For example if on the network
via a cellular phone connection. The second is if the "vehicle" is a
simulated vehicle running on a user's laptop also with its IP address
set via DHCP. In both cases there may be another MOOS community with a
known IP address, e.g., a shoreside community, to which the local
vehicle wishes to inform it of its current IP address. This simple
process however does not get involved in any activity regarding the
communication to other MOOS communities, but simply tries to determine
and post, the IP address, e.g., \mvar{PHI\_HOST\_IP}
\msvar{="192.168.0.1"} for other applications to do as they see fit.

%===================================================================
\section{Configuration Parameters for pHostInfo}
%===================================================================
%\index{pHostInfo!Configuration Parameters}
%\index{Configuration Parameters!pHostInfo}

The \app{pHostInfo} application may be configured with a configuration
block within a MOOS mission file, typically with a \var{.moos} file
suffix.  The following parameters are defined for \app{pHostInfo}.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for pHostInto}
\label{lst_phi_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.76\textwidth}} 

  \pvar{temp\_file\_dir}: &amp; Directory where temporary files are
  written. Default is \var{"$\sim$/"}. \\

  \pvar{default\_hostip}: &amp; IP address used if no IP address can
  otherwise be determined. \\

  \pvar{default\_hostip\_force}: &amp; This IP address will override any IP
  address from an auto-discovered network interface. Useful for
  debugging. \\

  \pvar{prefer\_inerface\_}: &amp; If multiple interfaces have a valid IP
  address then a preference can be specified. Valid options are
  \var{wlan0}, \var{wifi}, \var{eth0}, \var{eth1}, \var{usb0},
  \var{usb1},\var{usb2}. 

\end{longtable}
\end{listing}

%===================================================================
\subsection*{An Example MOOS Configuration Block}

An example MOOS configuration block may be obtained from the command line
with the following:

\begin{consoleverb}
 $ pHostInfo --example or -e 
\end{consoleverb}

\vspace{0.25in}
\begin{listing}{Example configuration of the pHostInfo application}
\label{lst_phi_econfig}
\footnotesize
\begin{verbatim}
  1  =============================================================== 
  2  pHostInfo Example MOOS Configuration                      
  3  ===============================================================
  4                            
  5  ProcessConfig = pHostInfo
  6  {             
  7    AppTick   = 4     
  8    CommsTick = 4    
  9                                                                  
 10    temp_file_dir  = ./
 11    default_hostip = 192.168.0.55    // default is "localhost"
 12    
 13    default_hostip_force = 192.168.0.99
 14  }                   
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Publications and Subscriptions for pHostInfo}
%===================================================================
%\index{pHostInfo!Publications and Subscriptions}
%\index{Publications and Subscriptions!pHostInfo}
\label{sec_phi_interface}

The interface for \app{pHostInfo}, in terms of publications and 
subscriptions, is described below. This same information may also be
obtained from the terminal with:

\begin{consoleverb}
 $ pHostInfo --interface or -i
\end{consoleverb}

%===================================================================
\subsection{Variables Published by pHostInfo}
\label{sec_phi_pubs}

The primary output of \app{pHostInfo} to the MOOSDB are the following
five \mvar{PHI\_*} variables. Once these variables are published,
\app{pHostInfo} does not publish them again unless requested by
receiving mail \mvar{HOST\_INFO\_REQUEST}. Thus \app{pHostInfo} is
mostly idle once the below five variables are posted.

\begin{packed_itemize}[2]

\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Appcasts are posted only after an appcast request
  is received from an appcast viewing utility. 

\item \mvar{PHI\_HOST\_IP}: The single best guess of the Host's IP
  address.

\item \mvar{PHI\_HOST\_IP\_ALL}: A comma-separated list of IP
  addresses if multiple addresses detected.

\item \mvar{PHI\_HOST\_IP\_VERBOSE}: A comma-separated list of IP
  addresses, with source information, if multiple addresses detected.

\item \mvar{PHI\_HOST\_PORT\_DB}: The port number of the MOOSDB for
  this community.

\item \mvar{PHI\_HOST\_PORT\_INFO}: A comma-separated list of
  parameter-value pairs describing all relevant aspects of the host.
\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by pHostInfo}
\label{sec_phi_subs}

The \app{pHostInfo} application subscribes to the following MOOS
variable:

\begin{packed_itemize}[2]
\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration. Section
  \ref{sec_ac_requests}.

\item \mvar{HOST\_INFO\_REQUEST}: A request to re-determine and
  re-post the platform's host information.

\item \mvar{PSHARE\_INPUT\_SUMMARY}: The input routes used by
  \app{pShare} for listening for incoming messages from other MOOSDBs.
\end{packed_itemize}

%===================================================================
\subsection{Command Line Usage of pHostInfo}
\label{sec_phi_cmdline}
%\index{Command Line Usage!pHostInfo}
%\index{pHostInfo!Command Line Usage}
%\index{Configuration Parameters!pHostInfo}
%\index{pHostInfo!Configuration Parameters}

The \app{pHostInfo} application is typically launched with pAntler,
along with a group of other modules. However, it may be launched
separately from the command line. The command line options may be
shown by typing:

\begin{consoleverb}
 $ pHostInfo --help or -h
\end{consoleverb}

\vspace{0.1in}
\begin{listing}{Command line usage for the pHostInfo tool}
\label{phi_usage}
\footnotesize
\begin{verbatim}
  1  Usage: pHostInfo file.moos [OPTIONS]             
  2                                                         
  3  Options:                                               
  4    --alias=&lt;ProcessName&gt;                                
  5        Launch pHostInfo with the given process    
  6        name rather than pHostInfo.                
  7    --example, -e                                        
  8        Display example MOOS configuration block         
  9    --help, -h                                           
 10        Display this help message.                       
 11    --HOSTIP=&lt;HostIP&gt;                                          
 12        Force the use of the given IP address as the reported IP  
 13        address ignoring any other auto-discovered IP address.    
 14    --interface, -i                                               
 15        Display MOOS publications and subscriptions.      
 16    --version,-v                                         
 17        Display the release version of pHostInfo.  
 18 
 19  Note: If argv[2] is not of one of the above formats 
 20        this will be interpreted as a run alias. This 
 21        is to support pAntler launching conventions.  
\end{verbatim}
\end{listing}
\normalsize
 
%===================================================================
\section{Usage Scenarios for the pHostInfo Utility}
%===================================================================

%===================================================================
\subsection{Handling Multiple IP Addresses}
\label{sec_phi_ordering}

It is possible that a machine has more than one valid IP address at
any given time, e.g., if its ethernet cable is plugged in, and it has
a wireless connection. In this case, \app{pHostInfo} will make a guess
that the ethernet connection takes precedent, and it will report this
in the variable \mvar{PHI\_HOST\_IP}. The full set of IP addresses can
be found in the other postings.  For example it may not be uncommon to
see something like the following three postings at one time:

\prevgreen
\begin{verbatim}
  PHI_HOST_IP         = 118.10.24.23
  PHI_HOST_IP_ALL     = 118.10.24.23,169.224.126.40
  PHI_HOST_IP_VERBOSE = OSX_ETHERNET2=118.10.24.23,OSX_AIRPORT=169.224.126.40
\end{verbatim}
\postverb[0in]

%===================================================================
\section{A Peek Under the Hood}
%===================================================================

The \app{pHostInfo} application currently only works for GNU/Linux and
Apple OS X.  It determines the IP information by making a system call
within C++. A system call when generated will act as if the argument
were typed on the command line. In this case the system call is
generated and the output is redirected to a file. In a second step,
\app{pHostInfo} then tries to read the IP address information from
those files.

\pskip 

In GNU/Linux, the system call is based on the \var{ifconfig}
command. In OS X, the system call is based on the \var{networksetup}
command.  Rather than determining in \app{pHostInfo} whether the user
is running in a GNU/Linux or OS X environment, the system calls for
both are invoked. Presumably a system call on a command not found in
the user's shell path will not generate something that is confusable
with a valid IP address.

%===================================================================
\subsection{Temporary Files}
%===================================================================

The temporary files are written to the user's home directory by
default. This may be changed with the \pvar{temp\_file\_dir}
cofiguration parameter, for example, \psvar{temp\_file\_dir=/tmp}.
The set of temporary files are put into a folder named
\var{.phostinfo/}.  The set of temporary files may look like:

\footnotesize
\begin{verbatim}
  $ cd ~/.phostinfo
  $ ls -a .ipinfo*
.ipinfo_linux_ethernet.txt    .ipinfo_osx_airport.txt     .ipinfo_osx_ethernet2.txt  
.ipinfo_osx_wifi.txt          .ipinfo_linux_wifi.txt      .ipinfo_osx_ethernet1.txt  
.ipinfo_osx_ethernet.txt
\end{verbatim}
\normalsize
 
Some of these files may be empty, or some may contain error output if
one of the system commands was not found, or was given an improper
argument. The \app{pHostInfo} app will try to parse all of them to
find a valid IP address. If more than one IP address is found, then
this handled in the manner described previously in Section
\ref{sec_phi_ordering}.

%===================================================================
\subsection{Possible Gotchas}

The system calls invoked by \app{pHostInfo} need to be in the users
shell path. A typical user default environment would have these in
their shell path anyway, but it may be worth checking if things aren't
working properly. Below is a list of commands that are run under the
hood, and their probable locations on your system.

\footnotesize
\begin{verbatim}
For Linux:
  /sbin/ifconfig
  /bin/grep
  /usr/bin/cut
  /usr/bin/awk
  /usr/bin/print
For OS X:
  /usr/sbin/networksetup
\end{verbatim}
\normalsize
 
\end{document}

</pre></body></html>