docs/network-scripts.tex

   1 \subsubsection{Using the network scripts}
   2
   3 To be able to access the network functions, you need to include
   4 the necessary shell scripts by running:
   5
   6 \begin{Verbatim}
   7 . /lib/functions.sh      # common functions
   8 include /lib/network     # include /lib/network/*.sh
   9 scan_interfaces          # read and parse the network config
  10 \end{Verbatim}
  11
  12 Some protocols, such as PPP might change the configured interface names
  13 at run time (e.g. \texttt{eth0} => \texttt{ppp0} for PPPoE). That's why you have to run
  14 \texttt{scan\_interfaces} instead of reading the values from the config directly.
  15 After running \texttt{scan\_interfaces}, the \texttt{'ifname'} option will always contain
  16 the effective interface name (which is used for IP traffic) and if the
  17 physical device name differs from it, it will be stored in the \texttt{'device'}
  18 option.
  19 That means that running \texttt{config\_get lan ifname}
  20 after \texttt{scan\_interfaces} might not return the same result as running it before.
  21
  22 After running \texttt{scan\_interfaces}, the following functions are available:
  23
  24 \begin{itemize}
  25     \item{\texttt{find\_config \textit{interface}}} \\
  26         looks for a network configuration that includes
  27         the specified network interface.
  28
  29     \item{\texttt{setup\_interface \textit{interface [config] [protocol]}}} \\
  30       will set up the specified interface, optionally overriding the network configuration
  31       name or the protocol that it uses.
  32 \end{itemize}
  33
  34 \subsubsection{Writing protocol handlers}
  35
  36 You can add custom protocol handlers (e.g: PPPoE, PPPoA, ATM, PPTP ...)
  37 by adding shell scripts to \texttt{/lib/network}. They provide the following
  38 two shell functions:
  39
  40 \begin{Verbatim}
  41 scan_<protocolname>() {
  42     local config="$1"
  43     # change the interface names if necessary
  44 }
  45
  46 setup_interface_<protocolname>() {
  47     local interface="$1"
  48     local config="$2"
  49     # set up the interface
  50 }
  51 \end{Verbatim}
  52
  53 \texttt{scan\_\textit{protocolname}} is optional and only necessary if your protocol
  54 uses a custom device, e.g. a tunnel or a PPP device.
  55