<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
<article>
  <title>ATA auto-provisioning</title>

  <section>
    <title>General</title>

    <para>This system allows you to plug an ATA into a network running VOCAL
    and have the ATA receive the necessary provisioning parameters to make
    calls in the system. This should work without user input.</para>

    <para>When the ATA is plugged into the network, it contacts a DHCP server.
    The DHCP server sends the ATA the address of a TFTP server and the ATA
    then requests its provisioning data from that TFTP server. The TFTP server
    makes an HTTP request to a CGI script that interacts with the VOCAL
    provisioning system to assign a new phone number to the ATA and discover
    the address of the User Agent Marshal the the ATA must register with. The
    CGI script makes sure the new user is entered into VOCAL provisioning and
    compiles a complete set of provisioning data for the ATA, then returns
    that data converted into the binary format that is readable by the ATA.</para>

    <para>Once the ATA has been provisioned in this manner, it registers with
    the User Agent Marshal and is ready to make and receive calls in the VOCAL
    system.</para>
  </section>

  <section>
    <title>DHCP Server</title>

    <para>I only managed to get a very primitive DHCP configuration to work,
    but here it is:</para>

    <programlisting># inserted for auto-provisioning ATAs with VOCAL
group{
option tftp-server-name &#34;vvs-jaco&#34;;

host ata1 { hardware ethernet 00:07:0e:dc:eb:df; }
}

group{
option tftp-server-name &#34;vvs-jaco&#34;;

host ata2 { hardware ethernet 00:07:0e:dc:f8:a8; }
}

group{
option tftp-server-name &#34;vvs-jaco&#34;;

host ata3 { hardware ethernet 00:08:a3:96:2f:81; }
}
</programlisting>

    <section>
      <title>Recognizing an ATA Request</title>

      <para>To get the DHCP server to recognize an ATA request, it may be
      possible to use blocks of MAC addresses that have been assigned to the
      ATA. At this time there is some uncertainty about what all those blocks
      are. The 2 blocks that I have seen are 00070e and 0008a3. These blocks
      are assigned to Cisco, but I do not know if they are used exclusively
      for the ATA. A more promising solution would be to use option 60 to
      identify ATA boxes. I quote from the Administrator/Developer
      Provisioning Guide to Cisco ATA 186/182: The Dhcp server can use option
      60 to identify ATA boxes (Option 60, DHCP_VENDOR_CLASS_ID, is set to the
      value &#34;ATA186&#34; and ATA182&#34; respectively for CISCO ATA 186
      and Cisco ATA 182).I do not know how to get the syntax to work for this.
      The only successful test I made with the DHCP server was by hard-coding
      the MAC address of each ATA into dhcpd.conf.</para>
    </section>

    <section>
      <title>Sending TFTP address</title>

      <para>The DHCP server must send the ATA the address of a TFTP server
      that is set up to get data from an HTTP request instead of a file. See
      the following section. To set this up, use the following syntax in
      dhcpd.conf:<command>option tftp-server-name &#34;name of server&#34;;</command></para>
    </section>
  </section>

  <section>
    <title>TFTP Server</title>

    <para>Bryan and Cullen have made modifications to TFTP source to provide a
    -h option, which causes the server to send the results of an HTTP request
    instead of a file. The new binary for the TFTP server is difficult to
    compile, but check with Bryan on how to get it. You must put a tftp entry
    into /etc/xinetd.d with the -h option for server_args. Following is a
    sample tftp configuration:</para>

    <para>Note: on RedHat 7.3, create a file /etc/xinitd.d/tftp and put the
    sample configuration.</para>

    <programlisting># default: on
# description: An http-enabled tftp server \

service tftp
{
  socket_type = dgram
  protocol    = udp
  wait        = yes
  user        = root
  server      = /usr/sbin/in.tftpd
  server_args = -h http://localhost/vocalconf/private/atatftp.pl/ -u nobody -s /
  disable     = no
  flags       = NOLIBWRAP
  passenv     = 
  log_type    = SYSLOG daemon info
  log_on_failure = HOST EXIT 
  log_on_success = HOST EXIT
}</programlisting>

    <para>To install the TFTP server, you must first install tftp from some
    other installation package, such as an RPM. Note that the configuration
    file above assumes that in.tftpd is located in /usr/sbin. Now replace
    /usr/sbin/tftpd.in with the modified tftp binary and restart xinetd.</para>
  </section>

  <section>
    <title>Apache</title>

    <para>The TFTP configuration file above instructs the TFTP server to use
    the command <command>http://localhost/vocalauto/atatftp.pl/</command> to
    get the data to service a request. The TFTP server will make an http
    request to execute the CGI script atatftp.pl at location /vocalauto/ on
    localhost. Note that it will pass on the MAC address string sent by the
    ATA in this request as well. You need to configure the Apache webserver to
    have an alias for vocalauto that is the true location of atatftp.pl.
    Because the call to the CGI script is all automatic, there is no way to
    provide security. The access to vocalauto must be unrestricted. For this
    reason you should put atatftp.pl in a directory of its own so that other
    cgi scripts cannot be executed without authentication. I made a directory
    called cgi-bin2 and put atatftp.pl there. Following is the entry in
    httpd.conf that sets up the vocalauto alias:</para>

    <programlisting>########################################
## Added by autoprovisioning
## vocalkey: auto v1.2
########################################
&#60;Directory &#34;/usr/local/vocal/cgi-bin/private/&#34;&#62;
    AllowOverride None
    Options ExecCGI
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
&#60;/Directory&#62;
########################################
## vocalkeyend: auto v1.2
########################################</programlisting>
  </section>

  <section>
    <title>CGI Script</title>

    <section>
      <title>Requests and Responses</title>

      <para>There are 3 possible request strings that the ATA can send to the
      TFTP server. These strings are passed on to the CGI script in the
      path_info:</para>

      <itemizedlist>
        <listitem>
          <para>the MAC address of the ATA prefaced by &#34;ata&#34;. The CGI
          script responds by returning the provisioning data for that ATA.</para>
        </listitem>

        <listitem>
          <para>the name of a zup file. A zup file is a software image for the
          ATA. The CGI script responds by returning the contents of the zup
          file.</para>
        </listitem>

        <listitem>
          <para>a garbage string set by the DHCP server. The DHCP server can
          cause the ATA to send a fixed string instead of its MAC address when
          it requests its provisioning data. Right now that string is assumed
          to contain the word &#34;bootp&#34;. The CGI script responds by
          returning provisioning data that only sets the OpFlags field so that
          on the next request the ATA will send its MAC address</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Zup File</title>

      <para>A zup file is a sofware image for the ATA. ATAs are going to be
      shipped with a stripped-down software image that does not handle SIP, so
      it will be necessary to load a SIP-enabled software image onto them. The
      zup file must be located in /usr/local/vocal/etc, but we do not
      distribute it. It will be up to the person deploying this system to get
      the zup file from CCO.</para>
    </section>

    <section>
      <title>Provisioning Data</title>

      <para>The CGI script keeps a list of MAC addresses that it has seen,
      with the VOCAL userid that has been assigned to each one. When it gets a
      MAC address request, it checks this list to see if there is already a
      userid assigned to that MAC address. If there is, it retrieves the
      provisioning data from VOCAL provisioning. If there is not, it creates a
      new userid, making sure that this userid is not already in VOCAL
      provisioning, and sets up default provisioning parameters. It determines
      the address of the User Agent Marshal and includes that in the default
      provisioning data. It then saves this data in VOCAL provisioning, so
      that the new userid will be recognized when the ATA registers with
      VOCAL.</para>

      <para>The CGI script uses a conversion utility provided with the ATA to
      convert the text provisioning data into the binary form required by the
      ATA before returning the data to the TFTP server, which relays it back
      to the ATA.</para>
    </section>

    <section>
      <title>Set-Up</title>

      <para>Following is the list of files that need to be copied to locations
      under /usr/local/vocal.</para>

      <table>
        <title>Deployment of Files</title>

        <tgroup cols="3">
          <thead>
            <row>
              <entry>filename</entry>

              <entry>description</entry>

              <entry>location</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>atatftp.pl</entry>

              <entry>CGI script</entry>

              <entry>/usr/local/vocal/cgi-bin/private/</entry>
            </row>

            <row>
              <entry>cfgfmt</entry>

              <entry>conversion utility for ATA</entry>

              <entry>/usr/local/vocal/bin/ **</entry>
            </row>

            <row>
              <entry>ptag.dat</entry>

              <entry>data file used by cfgfmt</entry>

              <entry>/usr/local/vocal/bin/ **</entry>
            </row>

            <row>
              <entry>mac_addresses</entry>

              <entry>list of MAC addresses</entry>

              <entry>/usr/local/vocal/provisioning_data/</entry>
            </row>

            <row>
              <entry>ataParams.txt</entry>

              <entry>default provisioning template</entry>

              <entry>/usr/local/vocal/etc/</entry>
            </row>

            <row>
              <entry>ataOpFlags.txt</entry>

              <entry>template for changing OpFlags</entry>

              <entry>/usr/local/vocal/etc/</entry>
            </row>

            <row>
              <entry>ata186-vx-xx-xxxxxxa.zup</entry>

              <entry>software image</entry>

              <entry>/usr/local/vocal/etc/ **</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <note>
        <para>** We do not supply these files. They must be downloaded from
        CCO</para>
      </note>

      <para>The CGI script creates several temporary files, located in /tmp.
      Normally these files are deleted by the CGI script when it is finished
      with them. You may turn on the debug option in the script to stop
      .atalog and .atatxt from being deleted for debugging. Note that if any
      files are left undeleted, they will be owned by the last user to run the
      CGI script. This will be user Nobody if the CGI script was last run by
      Apache. If a different user attempts to run the CGI script without first
      deleting the files, then it will fail.</para>

      <table>
        <title>Temp Files</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry>temp filename</entry>

              <entry>description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>.atatftp.lock</entry>

              <entry>used to block multiple concurrent execution of CGI script</entry>
            </row>

            <row>
              <entry>.atalog</entry>

              <entry>logs messages written to STDERR -- very useful for
              discovering why the CGI script is dying</entry>
            </row>

            <row>
              <entry>.atatxt</entry>

              <entry>contains text of the last provisioning data sent to an
              ATA</entry>
            </row>

            <row>
              <entry>.atabin</entry>

              <entry>output from cfgfmt -- this is the binary data returned to
              the ATA</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
  </section>

  <section>
    <title>Outstanding Issues</title>

    <para>Pserver now requires a password. The password is same as the
    password one has chosen for vocal provisioning.For now edit the file
    /usr/local/vocal/cgi-bin/private/atatftp.pl and replace the word
    &#34;hello&#34; with the vocal password. In future the password would be
    retrieved from a config file.</para>
  </section>
</article>