File contents

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter lang="en-US" id="UsingdCacheToCopy">
    <title>Using dCache to Copy Files to/from Enstore</title>

    <para>Whenever a client application needs to talk to the dCache, it has to
    choose an appropriate door into the system. For each door, there are
    corresponding utilities for copying files back and forth between your
    machine and your <filename
    class="directory">/pnfs/storage-group</filename> area on the machine
    running dCache. We describe how to use the supported utilities in this
    chapter.</para>

    <para>Each dCache server may have multiple doors, thus allowing a variety
    of access methods. Each door is limited to about 50 simultaneous
    transfers; more doors can be added as needed. The dCache supports Kerberos
    V5 for FTP, the dCache native dCap C-API, and GSI FTP.</para>

    <caution>
      <para>The dCache server node and the ports documented in this section
      are subject to change. You can always find the <ulink
      url="http://www-isd.fnal.gov/enstore/dcache_user_guide.html">current
      configuration from the web page</ulink>.</para>
    </caution>

    <section id="dCacheNativedCap">
      <title>dCache-Native dCap</title>

      <para><firstterm>dCap</firstterm> is a dCache-native access protocol.
      The dCap client, <application>dccp</application>, is available at the
      <ulink url="ftp://fnkits.fnal.gov/products/dcap/">KITS ftp site</ulink>.
      The libdcap library provides POSIX-like open, create, read, write and
      lseek functions to the dCache storage. In addition there are some
      specific functions for setting debug level, getting error messages, and
      binding the library to a network interface. See the <ulink
      url="http://www-dcache.desy.de/manuals/libdcap.html">dCache manual for
      usage information</ulink>.</para>
    </section>

    <section id="AuthenticationMechanisms">
      <title>Authentication Mechanisms</title>

      <para>There are three authentication mechanisms used for the dcap
      protocol:</para>

      <orderedlist>
        <listitem>
          <para><link linkend="PlainDcap">Plain</link></para>
        </listitem>

        <listitem>
          <para><link linkend="KerberizedDcap">Kerberos</link></para>
        </listitem>

        <listitem>
          <para><link linkend="X509Dcap">X509</link></para>
        </listitem>
      </orderedlist>

      <para>All three have separate port numbers and separate "setup dcap"
      qualifiers for the UPS/UPD distribution of dCap. CDF has both kerberized
      dcap and X.509 dcap.</para>

      <para>These different qualifiers have to be setup correctly in UPS for
      this to work though, with a ups listing for each qualifier state. For
      debugging this issue, the env var DCACHE_IO_TUNNEL should point to the
      appropriate shared library for the authentication mechanism: a file like
      libgsstunnnel.so for krb5, libgsitunnel.so for x509, and it should be
      unset for plain dcap access.</para>

      <section id="PlainDcap">
        <title>Plain dCap</title>

        <para>Plain dCap is strictly limited to fnal.gov domain access only.
        It uses uid/gid permissions on files in PNFS. Plain dcap is not the
        same as weakly-authenticated FTP, as it does allow write access as
        one's uid/gid permits. On FNDCA1, plain dcap is available on
        fndca1.fnal.gov:24125 and 24136. The UPS setup command reads:</para>

        <para><userinput>$ setup dcap -q unsecured</userinput></para>
      </section>

      <section id="KerberizedDcap">
        <title>Kerberized dCap</title>

        <note>
          <para>If your dCap door uses Kerberos V5 authentication, you must
          have a Kerberos principal for the FNAL.GOV realm.</para>
        </note>

        <para>Kerberized dcap is available on ports 24725, 24736 to anyone
        with valid FNAL.GOV kerberos credentials. Install the dCap product on
        your computer. See the <ulink
        url="http://www-dcache.desy.de/manuals/dcap_setup.html">dCap Setup
        Manual</ulink>.</para>

        <para>The UPS setup command reads simply:</para>

        <para><userinput>setup dcap</userinput></para>

        <para>Besides creating a certificate with the "kx509", you have to
        place the certificate in the correct format and the correct location.
        Please see <ulink
        url="http://security.fnal.gov/pki/Get-Personal-DOEGrids-Cert.html#globus"><citetitle
        pubwork="article">Using Globus tools for submitting grid jobs from
        Linux/UNIX</citetitle></ulink> for the current suggested means of
        doing this.</para>
      </section>
    </section>

    <section id="NodesAndPorts">
      <title>Nodes and Ports</title>

      <para>The nodes and ports available for dCap are subject to change; to
      get a current listing, run the following command, using your storage
      group (sample output shown for storage group cdfen):</para>

      <screen>% cat '/pnfs/cdfen/.(config)(dCache)(dcache.conf)'
cdfdca1.fnal.gov:25125
cdfdca1.fnal.gov:25136
...
cdfdca2.fnal.gov:25153
cdfdca2.fnal.gov:25154
cdfdca3.fnal.gov:25155
...</screen>

      <para>The dCap protocol requires specification of the dCache server
      host, port number, and domain, in addition to the inclusion of “/usr”
      ahead of the storage group designation in the PNFS path. Its structure
      is shown here:</para>

      <synopsis>dcap://<replaceable>serverHost</replaceable>:<replaceable>port</replaceable>/&lt;/pnfs&gt;/<replaceable>storage_group</replaceable>/usr/<replaceable>filePath</replaceable></synopsis>

      <para>There are supposed to be two slashes inbetween the port number and
      pnfs (e.g., .. :24124//pnfs/...) but since users frequently just put one
      slash, we’ve allowed either one or two.</para>

      <note>
        <para>If you run any of the following commands
        (<command>dccp</command>, <command>dc_check</command>,
        <command>dc_stage</command>) and it fails because the port is
        unavailable, try the command again with a different port number, or
        with a different host and port combination.</para>
      </note>
    </section>

    <section id="Dccp">
      <title>dccp</title>

      <para><command>dccp</command>, which is available in the dCap product,
      provides a cp-like functionality on the pnfs file system. It has the
      following syntax:</para>

      <cmdsynopsis>
        <command>dccp</command>

        <arg>-d <replaceable>debuglevel</replaceable></arg>

        <arg>-h <replaceable>relpyHostName</replaceable></arg>

        <arg>-i</arg>

        <arg>-S</arg>

        <sbr />

        <arg>-P <arg>-t <replaceable>time</replaceable></arg><arg>-l
        <replaceable>location</replaceable></arg></arg>

        <arg>-b <replaceable>read-ahead bufferSize</replaceable></arg>

        <sbr />

        <arg>-B <replaceable>bufferSize</replaceable></arg>

        <arg>-u</arg>

        <arg>-w</arg>

        <arg>-p
        <replaceable>first-port</replaceable><arg>:last-port</arg></arg>

        <sbr />

        <arg>-T <replaceable>IO tunnel plugin</replaceable></arg>

        <arg choice="req"><replaceable>source</replaceable></arg>

        <arg><replaceable>destination</replaceable></arg>
      </cmdsynopsis>

      <para>See the <citetitle pubwork="book">dCache Manual</citetitle> for
      more on <ulink url="http://www-dcache.desy.de/manuals/dccp.html">options
      and command usage</ulink>.</para>
    </section>

    <section id="Dc_stage">
      <title>dc_stage</title>

      <para><command>dc_stage</command> prestages the request; for read
      requests only. It is particularly useful when you’d like to grab the
      file quickly from the dCache when you’re ready for it. Use this with the
      <option>-t</option> option to set an interval of time between the
      download to the dCache and the download from the dCache to your local
      system. If <option>-t</option> is not used, the default interval is
      zero.</para>

      <cmdsynopsis>
        <command>dc_stage</command>

        <arg>-t <replaceable>number of seconds</replaceable><arg
        choice="req"><replaceable>source</replaceable></arg><arg><replaceable>destination</replaceable></arg></arg>
      </cmdsynopsis>
    </section>

    <section id="Dc_check">
      <title>dc_check</title>

      <para>The <command>dc_check</command> command checks if a file is on
      disk in the <filename>dCache.dc_check</filename> file</para>
    </section>

    <section>
      <title>PNFS Not Mounted Locally: Syntax and Examples</title>

      <para>If PNFS is not mounted locally (the general case), you’ll have to
      supply the protocol, node, port, and pnfs directory for the remote
      location (the “source” on reads, and the “destination” on
      writes).</para>

      <section id="RequestingAWriteToEnstore">
        <title>Requesting a write to Enstore</title>

        <screen>% dccp path/to/local/file \
  dcap://&lt;serverHost&gt;:&lt;port&gt;///pnfs/fnal.gov/usr/
  &lt;storage_group&gt;/&lt;filePath&gt;
</screen>
      </section>

      <section id="RequestingAWriteFromLocal">
        <title>Requesting a write from your local /tmp directory</title>

        <screen>% dccp /tmp/myfile \
  dcap://cdfdca1.fnal.gov:25140//pnfs/fnal.gov/usr/cdfen/x/myfile
</screen>
      </section>

      <section id="CheckingIfFileWithDc_check">
	<title>Checking if a file is on disk in the dCache by running dc_check</title>
	
        <screen>% dc_check \
   dcap://fndca1.fnal.gov:24725//pnfs/fnal.gov/myfile
</screen>

        <para>For a read rather than a write:</para>

        <screen>% dccp \
   dcap://cdfdca1.fnal.gov:25140//pnfs/fnal.gov/usr/cdfen/x/myfile \
   /tmp/myfile
</screen>
      </section>

      <section id="Pre-staginRequest">
        <title>Pre-staging this request with an hour interval using
        dc_stage:</title>

        <screen>% dc_stage -t 3600 \
   dcap://cdfdca1.fnal.gov:25140//pnfs/fnal.gov/usr/cdfen/x/myfile \
   /tmp/myfile
</screen>
      </section>
    </section>

    <section id="pnfsMountedLocally">
      <title>pnfs Mounted Locally: Syntax and Examples</title>

      <para>If pnfs is mounted on your local machine, you only need to specify
      the simple pnfs path of the remote file, e.g. (for a write):</para>

      <section id="SpecifyingPnfsPath">
        <title>Specifying the pnfs path of the remote file</title>

        <screen>% dccp path/to/local/file/pnfs/&lt;storage_group&gt;/&lt;filePath&gt;</screen>
      </section>

      <section id="WritingFileToEnstore">
        <title>Writing the file to Enstore</title>

        <para><screen>% dccp /tmp/myfile /pnfs/cdfen/x/myfile</screen></para>
      </section>

      <section id="ReadingFileFromEnstore">
        <title>Reading the file from Enstore</title>

        <para><screen>% dccp /pnfs/cdfen/x/myfile /tmp/myfile</screen></para>
      </section>
    </section>

    <section id="GridGsiFtp">
      <title>Grid (GSI) FTP</title>

      <para>GSI stands for Grid Security Interface. GSI FTP uses Grid Proxies
      for authentication and authorization and is compatible with popular Grid
      middleware tools such as <command>globus-url-copy</command> (available
      in the <ulink url="http://www.globus.org/">Globus toolkit at
      Globus</ulink> or <command>sam_gridftp</command> in Kits). The dCache
      GSI FTP currently runs on port 2811 on the following door nodes
      (different nodes for different user groups):</para>

      <informaltable frame="all">
        <tgroup cols="2">
          <tbody>
            <row>
              <entry><para>General users</para></entry>

              <entry><para>fndca1</para></entry>
            </row>

            <row>
              <entry><para>CDF</para></entry>

              <entry><para>cdfdca1, cdfdca2, cdfdca3</para></entry>
            </row>

            <row>
              <entry><para>CMS</para></entry>

              <entry><para> cmsdca1, cmsdca2 and cmsdca3 </para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>It is more convenient to run this through an interface like srmcp
      which allows you to perform multiple transfers in a single command. In
      addition, it optimizes the parameters of the transfer, and allows FTP to
      scale with user load (overcoming a passive gridftp protocol
      issue).</para>
    </section>

    <section id="ObtainGridProxies">
      <title>Obtain Grid Proxies</title>

      <para>Globus tools require that a user be authenticated with a
      short-term authentication Grid proxy. This proxy is created from
      (long-term) X.509 credentials issued by the <ulink
      url="http://www.doegrids.org/">DOE science grid</ulink> or <ulink
      url="http://computing.fnal.gov/security/pki">other Certificate
      Authority</ulink>, or from Kerberos credentials at Fermilab. DOE science
      grid is the recommended source for an X.509 certificate. We recommend
      that you use the command grid-proxy-init to generate your proxy from
      your certificate. A proxy expires after a preset duration, and then a
      new one must be regenerated from the user’s (long-term) X.509
      certificate.</para>

      <para>X.509 Grid proxies can be issued automatically for Fermilab users
      authenticated to Kerberos. (See <ulink
      url="http://computing.fnal.gov/security/pki/">Fermilab
      instructions</ulink>. This involves downloading a KX.509 certificate.
      KX.509 can be used in place of permanent, long-term certificates. It
      works by creating X.509 credentials (certificate and private key) using
      your existing Kerberos ticket. These credentials are then used to
      generate the Globus proxy certificate. <ulink
      url="http://www.ncsa.uiuc.edu/~aloftus/NMI/kx509.html">More on
      KX.509</ulink>.</para>
    </section>

    <section id="GsiFtpWithGlobus-url-copy">
      <title>GSI FTP with globus-url-copy</title>

      <para>Install the <ulink url="http://www.globus.org/">Globus
      toolkit</ulink>. Run the <command>globus-url-copy</command> command in
      order to use the GSI FTP protocol to transfer files. Use the
      <computeroutput>gsiftp://</computeroutput> URL prefix for the PNFS
      (Enstore) path, and <computeroutput>file://</computeroutput> for the
      other URL.</para>

      <para>For example, to copy from Enstore:</para>

      <screen>% globus-url-copy \
   gsiftp://[[&lt;src_node&gt;:]port]/&lt;source_url_path&gt; \
   file://[[&lt;dest_node&gt;]:port]/&lt;dest_url_path&gt;</screen>

      <para>To copy to Enstore:</para>

      <screen>% globus-url-copy \
   file://[[&lt;src_node&gt;:]port]/&lt;source_url_path&gt; \
   gsiftp://[[&lt;dest_node&gt;]:port]/&lt;dest_url_path&gt;</screen>

      <para>For a CDF user copying from Enstore to a local disk:</para>

      <screen>% globus-url-copy \
   gsiftp://cdfdca1.fnal.gov:2811/&lt;pnfs_path&gt; \
   file://&lt;local_url_path&gt;</screen>

      <para>Copying from one Enstore system to another (here, from CDFDCA to
      FNDCA):</para>

      <screen>% globus-url-copy
   gsiftp://cdfdca1.fnal.gov:2811/&lt;pnfs_path&gt;\
   gsiftp://fndca1.fnal.gov:2811/&lt;pnfs_path&gt;</screen>
    </section>

    <section id="StorageResourceMgt">
      <title>Storage Resource Management (SRM)</title>

      <para>SRM is middleware for managing storage resources on a grid. The
      SRM implementation within the dCache manages the dCache/Enstore system.
      It provides functions for file staging and pinning, transfer protocol
      negotiation and transfer url resolution.</para>

      <note>
        <para>Pinning refers to making a file undeletable in the cache for the
        period of time called the “lifetime of the job”.</para>
      </note>

      <para>The SRM client srmcp provides a convenient way to transfer
      multiple files from/to Enstore via dCache using a variety of protocols.
      <ulink url="http://grid.fnal.gov/">More on SRM...</ulink></para>

      <para>Srmcp is the implementation of SRM client as specified by the
      <ulink
      url="http://sdm.lbl.gov/srm/documents/joint.docs/srm.v1.0.doc">SRM
      spec</ulink>. You can use srmcp for the retrieval and/or storage of
      files to/from Enstore (or other Mass Storage Systems which implement
      SRM, e.g., <acronym>SLAC</acronym>’s, <acronym>CERN</acronym>’s). In
      this document we focus on file transfers to/from Fermilab’s Enstore via
      dCache.</para>

      <section id="PreparingToUseSrmcp">
        <title>Preparing to Use srmcp</title>

        <para>Two packages are available, one with java (srmcp), the other
        with a C-based client (srmtools); they are both in <ulink
        url="ftp://fnkits.fnal.gov:8021/products/">Kits</ulink>. To use the
        java-based srmcp, you will need to install java on your system. You
        will also need to install either the globus toolkit or dccp, depending
        on which protocol you wish to use. In order to use GSI with srmcp,
        follow the instructions in the README.SECURITY file that comes with
        srmcp in Kits.</para>
      </section>

      <section id="CommandSyntax">
        <title>Command Syntax</title>

        <cmdsynopsis>
          <command>srmcp</command>

          <arg>options</arg>

          <arg choice="req">source(s)</arg>

          <arg choice="req">destination</arg>
        </cmdsynopsis>

        <para>Default options will be read from a configuration file but can
        be overridden by command line options. The options are listed and
        defined in the srmcp README file in Kits. We do not list them
        here.</para>

        <para>The SRM protocol, used for the remote file specification,
        requires the SRM server host, port number, and domain. For the
        fnal.gov domain, the inclusion of “/usr” ahead of the storage group
        designation in the PNFS path is also required.</para>

        <para><userinput>srm://<replaceable>serverHost</replaceable>:<replaceable>portNumber</replaceable>/<replaceable>root
        of
        filesystem</replaceable>/<replaceable>storage_group</replaceable><optional>/usr</optional>/<replaceable>filepath</replaceable></userinput></para>

        <para>Some examples, the first two for the fnal.gov domain, the third
        for cern.ch:<itemizedlist>
            <listitem>
              <para><userinput>srm://cdfdca1.fnal.gov:8443//pnfs/fnal.gov/usr/cdfen/filesets/<replaceable>filePath</replaceable></userinput></para>
            </listitem>

            <listitem>
              <para><userinput>srm://fndca1.fnal.gov:8443//pnfs/fnal.gov/usr/<replaceable>filePath</replaceable></userinput></para>
            </listitem>

            <listitem>
              <para><userinput>srm://wacdr002d.cern.ch:9000/castor/cern.ch/user/<replaceable>filePath</replaceable></userinput></para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section id="Examples">
        <title>Examples</title>

        <para>These examples are taken from the srmcp v1_2 README file in Kits
        (with unnecessary options removed).</para>

        <para>The following command will retrieve two files,
        <filename>/mypath/myfile1.ext</filename> and
        <filename>/mypath/myfile2.ext</filename>, from Enstore via dCache (for
        a CDF user) and store them in the user’s local directory <filename
        class="directory">/home/me/targetdir</filename>. </para>

        <para>Note that srmcp requires that the PNFS path include <filename
        class="directory">/pnfs/fnal.gov/usr/</filename> ahead of the storage
        group designation.</para>

        <screen>% srmcp \
   srm://cdfdca1.fnal.gov:8443//pnfs/fnal.gov/usr/cdf/myfile1.ext \
   srm://cdfdca1.fnal.gov:8443//pnfs/fnal.gov/usr/cdf/myfile2.ext \
   file://localhost//home/me/targetdir
</screen>

        <para>The following will copy the same files from one Enstore
        installation (CDFEN) to another (STKEN):</para>

        <screen>% srmcp \
   srm://cdfdca1.fnal.gov:8443//pnfs/fnal.gov/usr/cdf/myfile1.ext \
   srm://cdfdca1.fnal.gov:8443//pnfs/fnal.gov/usr/cdf/myfile2.ext \
   srm:/fndca1.fnal.gov:8443/targetdir
</screen>

        <para>The following will get the file using dccp client, overriding
        the default (dccp would have to be already installed on you
        machine):</para>

        <screen>% srmcp \
   -protocols=dcap \
    srm:/fndca1.fnal.gov:8443//pnfs/fnal.gov/usr/targetdir/myfile1.ext \
    file:////tmp/myfile1.ext
</screen>

        <note>
          <para>The four slashes in the last line refer to:
          <computeroutput>file://</computeroutput> ; host, which comes next,
          is “ ”; path is</para>

          <para><userinput>/tmp/....
          <replaceable>[your_login_id@]</replaceable>fndcal:
          <replaceable>pnfs_path</replaceable>
          <replaceable>/path/to/local_file</replaceable></userinput></para>
        </note>
      </section>
    </section>

    <section id="X509Dcap">
      <title>X.509 dCap</title>

      <para>X.509 dcap is available on ports 24525, 24536. The UPS setup
      command reads:</para>

      <screen>$ setup dcap -q x509</screen>

      <para>For authentication to work, the environment variable X509_CERT_DIR
      must be set. If not, check with the compute administrator to get globus
      setup correctly for your job.</para>
    </section>

    <section id="GsiFtpWithKftcp">
      <title>GSI FTP with kftpcp <emphasis>(Deprecated)</emphasis></title>

      <para>GSI FTP is also available with kftpcp (see <xref
      linkend="KerberizedFtpVia" xreflabel="Title_KerberizedFtpVia" />).
      Install and setup kftp (<ulink type="FTP"
      url="ftp://fnkits.fnal.gov:8021/products/kftp">from Kits</ulink>). Also
      from kits, install and setup <command>gsspy_gsi</command> (for Grid
      proxy) instead of <command>gsspy_krb</command>. Kftpcp works the same as
      described in section 5.4 except that the port number is 2811 in this
      case.</para>

      <para>We refer you to section 5.4 for details, but here’s a quick
      example for a general user (using STKEN) to copy from Enstore to a local
      disk:</para>

      <para><command>% kftpcp -p 2811 -m p [-v]</command></para>
    </section>

    <section id="SimpleKerberizedFtp">
      <title>Simple Kerberized FTP</title>

      <para>The dCache door for Kerberized ftp service enforces Kerberos
      authentication (see the <ulink
      url="http://computing.fnal.gov/docs/strongauth/">Strong Authentication
      at Fermilab Documentation</ulink>). It currently runs on the following
      nodes and corresponding ports:</para>

      <orderedlist>
        <listitem>
          <para>fndca1.fnal.gov, port 24127 (for STKEN)</para>
        </listitem>

        <listitem>
          <para>cdfdca1, 2 and 3, port 25127 (for CDFEN)</para>
        </listitem>
      </orderedlist>

      <para>The port number is installation-specific.</para>

      <para>Any Kerberized ftp client can be used on the client machine. You
      must specify the host port in your ftp command.</para>

      <caution>
        <para>File read and write functionality is supported when the user (a)
        is authorized by the experiment to access the data stores, and (b) has
        obtained Kerberos credentials.</para>
      </caution>

      <important>
        <para>Portal Mode (CRYPTOCard) access is not supported since it is not
        compatible with automated transfers or future GRID development.</para>
      </important>
    </section>

    <section id="PrepareToUseKerberizedFtp">
      <title>Prepare to use Kerberized FTP</title>

      <para>In order to establish the kftp service on dCache, you must
      first:</para>

      <itemizedlist>
        <listitem>
          <para>Have a valid Fermilab UNIX account (UID and GID)</para>
        </listitem>

        <listitem>
          <para>Have a Kerberos principal for FNAL.GOV (if Kerberized access
          is required)</para>
        </listitem>

        <listitem>
          <para>Ask your experiment’s Enstore liaison to register you for the
          service. You will need to provide the following information to the
          liaison:</para>

          <orderedlist>
            <listitem>
              <para>username</para>
            </listitem>

            <listitem>
              <para>UID and GID (run the command id at the UNIX prompt to find
              their values)</para>
            </listitem>

            <listitem>
              <para>storage group</para>
            </listitem>

            <listitem>
              <para>root path under <filename
              class="directory">/pnfs/<replaceable>&lt;storage_group&gt;</replaceable>/...</filename></para>
            </listitem>

            <listitem>
              <para>Kerberos principal(s), if applying for Kerberized
              door</para>
            </listitem>

            <listitem>
              <para>password, if applying for weak door (request by emailing
              <email>dcache-admin@fnal.gov</email>)</para>

              <warning>
                <para>This is for groups, not individuals.</para>
              </warning>
            </listitem>
          </orderedlist>
        </listitem>

        <listitem>
          <para><emphasis>Optional:</emphasis> Install the kftp product from
          KITS. kftp is useful for running scripts to transfer files. To do
          so, run:</para>

          <para><command>$ setup upd$ upd install -G "-c"
          kftp</command></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="SampleKerberizedFtpSession">
      <title>Sample Kerberized FTP session</title>

      <para>User is authenticated to Kerberos and authorized for the
      Kerberized dCache door (currently at fndca1.fnal.gov, port
      24127):</para>

      <screen>
% ftp fndca1.fnal.gov 24127

Connected to stkendca3a.fnal.gov.
220 FTPDoorIM+GSS ready
334 ADAT must follow
GSSAPI accepted as authentication type
GSSAPI authentication succeeded
Name (fndca:aheavey):
200 User aheavey logged in
Remote system type is UNIX.
Using binary mode to transfer files.
ftp&gt; cd aheavey/test3

250 CWD command succcessful. New CWD is
   &lt;/aheavey/test3&gt;
 
ftp&gt; ls
200 PORT command successful
150 Opening ASCII data connection for file list
dupl2
duplexps
226 ASCII transfer complete
ftp&gt; get duplexps
local: duplexps remote: duplexps
200 PORT command successful

150 Opening BINARY data connection for
/pnfs/fs/usr/test/aheavey/test3/duplexps

226 Closing data connection, transfer successful

42 bytes received in 0.033 seconds (1.2 Kbytes/s)

ftp&gt;
</screen>
    </section>

    <section id="KerberizedFtpVia">
      <title id="Title_KerberizedFtpVia">Kerberized FTP via the kftpcp
      Command</title>

      <para>In order to access data from a batch job or a background process,
      you should either use ftp client libraries (available from many
      sources), or the kftp package. This package includes a Kerberized client
      library and a GSI client library; you can use either. A regular ftp
      client (Kerberized or not) is an interactive program which is hard to
      use in batch mode.</para>

      <para>To use the product in a UPS environment as a Kerberized FTP
      client, first run:</para>

      <para><userinput>% setup gsspy_krb; setup kftp</userinput></para>

      <para>Then run the kftpcp command to copy one or more files. This
      command can be used from the shell or in a script.</para>
    </section>

    <section id="SyntaxAndOptions">
      <title>Syntax and Options</title>

      <synopsis>% kftpcp [&lt;options&gt;] <replaceable>source_file</replaceable> <replaceable>destination_file</replaceable> </synopsis>

      <para>The available options include:</para>

      <informaltable frame="all">
        <tgroup cols="2">
          <tbody>
            <row>
              <entry><para><option>-p <replaceable>port</replaceable></option>
              </para></entry>

              <entry><para>ftp server port number</para></entry>
            </row>

            <row>
              <entry><para><command><option>-m [ a | p
              ]</option></command></para></entry>

              <entry><para>ftp server mode. Active (default), or passive
              </para></entry>
            </row>

            <row>
              <entry><para><option>-v</option></para></entry>

              <entry><para>verbose mode</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <important>
        <para>If your login id is the same on fndca1 and your local system,
        and if they match your Kerberos principal, you can leave off
        <userinput>\<replaceable>&lt;your_fndca1_login_id\&gt;</replaceable>@</userinput>
        in front of <userinput>fndca1:</userinput> in the command.</para>
      </important>

      <important>
        <para>Depending on how your access is configured, typically you only
        need to specify the path to the remote file starting from the
        directory under your /pnfs// area. For example, to specify the remote
        file <filename>/pnfs/my_storage_group/path/to/file</filename> on the
        command line, enter only <userinput>/path/to/file</userinput>,
        including the initial slash. You can use the full specification
        (starting with <userinput>/pnfs//usr/</userinput>)</para>
      </important>
    </section>

    <section id="DownloadFile">
      <title>Download a File</title>

      <para>To download a stored data file from Enstore via the dCache, using
      fndca1 as a sample server host, run:</para>

      <para>% <userinput>kftpcp -p 24127 -m p <option>[-v]</option>
      <replaceable>login_id</replaceable>@fndca1:<replaceable>/path/to/remote_file</replaceable>
      <replaceable>/path/to/local_file</replaceable>&gt;</userinput></para>
    </section>

    <section id="UploadFile">
      <title>Upload a File</title>

      <para>To upload a new data file, again using fndca1, run:</para>

      <synopsis><userinput>kftpcp -p 24127 - m p [ -v ] <replaceable>/path/to/local_file</replaceable> [<replaceable>fndcal_login</replaceable>]@fndcal:<replaceable>/path/to/remote_file</replaceable></userinput>
</synopsis>
    </section>

    <section id="ExamplesDownloadFile">
      <title>Examples</title>

      <para>To read (download) the stored file
      <filename>/pnfs/storage_group/mydir/myfile</filename> into a local file
      of the same name, run:</para>

      <screen>% setup kftp
% kftpcp -p 24127 -m p -v myloginid@fndca1:/mydir/myfile \
   /path/to/myfile
   
   Transferred 42 bytes
</screen>

      <para>Or, if your usernames and principal all match, you could shorten
      it to:</para>

      <screen>% kftpcp -p 24127 -m p -v fndca1:/mydir/myfile /path/to/myfile
</screen>
    </section>

    <section id="WeaklyAuthedFtpService">
      <title>Weakly-Authenticated FTP Service (Read-only)</title>

      <para>The dCache weakly-authenticated ftp service currently runs on node
      the following nodes and corresponding ports:</para>

      <orderedlist>
        <listitem>
          <para>fndca1.fnal.gov, port 24126 (for STKEN).</para>
        </listitem>

        <listitem>
          <para>cdfdca1, 2, and 3, port 25126 (for CDFEN)</para>
        </listitem>
      </orderedlist>

      <para>This is read-only, and is not necessarily allowed by all
      experiments. This ftp service can be accessed by ordinary ftp client
      software. You must specify the host port in your ftp command, as shown
      below. The Enstore admin will have sent you an email to confirm your
      registration for this service, and included a password for it. This is a
      weak password. Log in with your username and password.</para>

      <section id="SampleWeaklyAuthenticatedReadOnlyFtpSession">
        <title>Sample weakly-authenticated read-only ftp session</title>

        <para id="text">Here we explicitly use a weakly-authenticated ftp
        client, <filename>/usr/bin/ftp</filename>, and make the connection to
        fndca port 24126. In the session, we first successfully retrieve a
        file called myfile, and secondly attempt to write a file trace.txt and
        (correctly) fail.</para>

        <screen>% /usr/bin/ftp fndca1.fnal.gov 24126

Connected to stkendca3a.fnal.gov.
220 FTPDoorIM+PWD ready (read-only server)
Name (fndca:aheavey):
331 Password required for aheavey.
Password: XXXXXXXXXXXXXXX
230 User aheavey logged in
ftp&gt; cd aheavey/test3

 250 CWD command succcessful. New CWD is
 &lt;/aheavey/test3&gt;

ftp&gt; ls
 200 PORT command successful

 150 Opening ASCII data connection for file list

 myfile
 myfile2
 myfile3
 226 ASCII transfer complete

 10 bytes received in 0.018 seconds (0.55 Kbytes/s)

ftp&gt; get myfile
200 PORT command successful
150 Opening BINARY data connection for
/pnfs/fs/usr/test/aheavey/test3/myfile

226 Closing data connection, transfer successful

local: myfile remote: myfile

42 bytes received in 0.05 seconds (0.82 Kbytes/s)

ftp&gt; put trace.txt
200 PORT command successful
500 Command disabled
ftp&gt; bye
</screen>

        <important>
          <para>If you need to change this password, send email to
          <email>dcache-admin@fnal.gov</email>.</para>
        </important>
      </section>
    </section>
</chapter>