install.xml

<?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.3/docbookx.dtd" [
<!ENTITY % sharedents SYSTEM "shared-entities.xml" >
<!ENTITY user-dcache "<systemitem class='username'>dcache</systemitem>">
<!ENTITY user-root "<systemitem class='username'>root</systemitem>">
%sharedents;
]>

<chapter id="in">

  <title>Installing &dcache;</title>

  <para>
    The first section describes the installation of a fresh &dcache;
    instance using RPM files downloaded from <ulink
    url="http://www.dcache.org">the &dcache; home-page</ulink>. It is
    followed by a guide to upgrading an existing installation. In both
    cases we assume standard requirements of a small to medium sized
    &dcache; instance without an attached <glossterm
    linkend="gl-tss">tertiary storage system</glossterm>. The third
    section contains some pointers on extended features.
  </para>

  <section id="in-install">
    <title>Installing a &dcache; instance</title>

    <para>
      In the following the installation of a &dcache;
      instance will be described.  The &chimera; name space provider,
      some management components, and the &srm; need a &psql; server
      installed. We recommend running this &psql; on the local
      node. The first section describes the configuration of a &psql;
      server. After that the installation of &chimera; and of the
      &dcache; components will follow. During the whole installation
      process root access is required.
    </para>

    <section id="in-install-prerequisites">
      <title>Prerequisites</title>

      <para>
        In order to install &dcache; the following requirements must be met:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            An RPM-based Linux distribution is required for the
            following procedure. For Debian derived systems we provide
            Debian packages and for Solaris the Solaris packages or
            the tarball.
          </para>
        </listitem>

        <listitem>
          <para>
           &dcache; requires Java 1.7 JRE. Please use the
           latest patch-level and check for upgrades frequently. It is
           recommended to use JDK as &dcache; scripts can make use of
           some extra features that JDK provides to gather more
           diagnostic information (heap-dump, etc). This helps when
           tracking down bugs.
          </para>
        </listitem>

        <listitem>
          <para>
            &psql; must be installed and running.  We recommend the
            use of &psql; version 9.2 (at least &psql; version 8.3 is
            required).
	  </para>
	    <important>
	      <para>
		 For good performance it is necessary to maintain and
		 tune your &psql; server. There are several good books
		 on this topic, one of which is <ulink
		 url="http://www.2ndquadrant.com/books/postgresql-9-0-high-performance"><citetitle>PostgreSQL
		 9.0 High Performance</citetitle></ulink>.
	      </para>
	    </important>
        </listitem>
      </itemizedlist>
    </section>

    <section id="in-install-installation">
      <title>Installation of the &dcache; Software</title>

      <para>
        The RPM packages may be installed right away, for example
        using the command:
      </para>
      <screen>&prompt-root; <userinput>rpm -ivh dcache-&dcache-package-version;.noarch.rpm</userinput></screen>

       <para>
       The actual sources lie at <ulink url="http://www.dcache.org/downloads/IAgree.shtml"/>.
       To install for example Version &dcache-package-version; you would use this:
        <screen>&prompt-root; <userinput>rpm -ivh http://www.dcache.org/downloads/1.9/repo/&dcache-version;/dcache-&dcache-package-version;.noarch.rpm</userinput></screen>
        The client can be found in the download-section of the above url, too.
        </para>

    </section>

    <section id="in-install-postgres">
      <title>Readying the &psql; server for the use with &dcache;</title>

      <para>
	Using a &psql; server with &dcache; places a number of requirements on the database.
        You must configure &psql; for use by &dcache; and create the
        necessary &psql; user accounts and database structure.  This
        section describes how to do this.
      </para>

      <section id="in-install-postgres-start">
	<title>Starting &psql;</title>
	<para>
	  Install the &psql; server with the tools of the operating
	  system.
	</para>

	<para>
	  Initialize the database directory (for &psql; version 9.2
	  this is <filename
	  class='dir'>/var/lib/pgsql/9.2/data/</filename>) , start the
	  database server, and make sure that it is started at system
	  start-up.
	</para>
	<screen>&prompt-root; <userinput>service postgresql-9.2 initdb</userinput>
Initializing database:                                     [  OK  ]
&prompt-root; <userinput>service postgresql-9.2 start</userinput>
Starting postgresql-9.2 service:                           [  OK  ]
&prompt-root; <userinput>chkconfig postgresql-9.2 on</userinput></screen>
      </section>

      <section id="in-install-postgres-trust">
	<title>Enabling local trust</title>

          <para>
            Perhaps the simplest configuration is to allow
            password-less access to the database and the following
            documentation assumes this is so.
          </para>

          <para>
            To allow local users to access &psql; without requiring a
            password, ensure the file
            <filename>pg_hba.conf</filename>, which (for &psql;
            version 9.2) is located in <filename
            class="directory">/var/lib/pgsql/9.2/data</filename>,
            contains the following lines.
          </para>

          <programlisting># TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust</programlisting>

          <note>
            <para>
              Please note it is also possible to run &dcache; with all
              &psql; accounts requiring passwords. See <xref
              linkend="cb-postgres-configure"/> for
              more advice on the configuration of &psql;.
            </para>
          </note>

          <important>
	    <title>Restarting &psql;</title>

	    <para>
            If you have edited &psql; configuration files, you
            <emphasis>must</emphasis> restart &psql; for those changes
            to take effect.  On many systems, this can be done with
            the following command:
	    </para>

	    <screen>&prompt-root; <userinput>service postgresql-9.2 restart</userinput>
Stopping postgresql-9.2 service:                           [  OK  ]
Starting postgresql-9.2 service:                           [  OK  ]</screen>
          </important>
        </section>

    </section>


    <section id="in-install-chimera">
      <title>Configuring &chimera;</title>

      <para>
	&chimera; is a library providing a hierarchical name space
	with associated meta data. Where pools in &dcache; store the
	content of files, &chimera; stores the names and meta data of
	those files. &chimera; itself stores the data in a relational
	database. We will use &psql; in this tutorial.  The properties
	of &chimera; are defined in
	<filename>&path-ods-usd;/defaults/chimera.properties</filename>.
	See <xref linkend="cf-chimera"/> for more information.
      </para>

      <section id="in-install-chimera-initDB">
	<title>Creating users and databases for &dcache;</title>
	<para>
	  Create the <database>Chimera</database> database and user.
	</para>

	<screen>&prompt-root; <userinput>createdb -U postgres chimera</userinput>
CREATE DATABASE
&prompt-root; <userinput>createuser -U postgres --no-superuser --no-createrole --createdb --pwprompt chimera</userinput>
Enter password for new role:
Enter it again:
<lineannotation>You do not need to enter a password.</lineannotation></screen>

      <para>
	The &dcache; components will access the database server with
	the user <database class="user">srmdcache</database>.
      </para>

      <screen>&prompt-root; <userinput>createuser -U postgres --no-superuser --no-createrole --createdb --pwprompt srmdcache</userinput>
Enter password for new role: 
Enter it again:
<lineannotation>You do not need to enter a password.</lineannotation></screen>

      <para>
	Several management components running on the head node as well
	as the &srm; will use the database <database>dcache</database>
	for storing their state information:
      </para>

      <screen>&prompt-root; <userinput>createdb -U srmdcache dcache</userinput></screen>

      <para>
	There might be several of these on several hosts. Each is used
	by the &dcache; components running on the respective host.
      </para>

      <para>
	Create the database used for the billing plots.
      </para>

      <screen>
&prompt-root; <userinput>createdb -O srmdcache -U postgres billing</userinput></screen>

      <para>
	And run the command <command>dcache database update</command>.
      </para>
      <screen>&prompt-root; <userinput>dcache database update</userinput>
PnfsManager@dCacheDomain: 
INFO  - Successfully acquired change log lock
INFO  - Creating database history table with name: databasechangelog
INFO  - Reading from databasechangelog
<lineannotation>many more like this...</lineannotation>
      </screen>

      <para>
	Now the configuration of &chimera; is done.
      </para>

      </section>

      <para>
	Before the first start of &dcache; replace the file
	<filename>&path-ode-ed;/gplazma.conf</filename> with an empty
	file.
      </para>
      <screen>&prompt-root; <userinput>mv &path-ode-ed;/gplazma.conf &path-ode-ed;/gplazma.conf.bak</userinput>
&prompt-root; <userinput>touch &path-ode-ed;/gplazma.conf</userinput></screen>
      <para>
	&dcache; can be started now.
      </para>

      <screen>&prompt-root; <userinput>&path-odb-n-s;dcache start</userinput>
Starting dCacheDomain done</screen>


      <para>
	So far, no configuration of &dcache; is done, so only the predefined domain is started.
      </para>

    </section>

    <section id="in-install-configure">
      <title>Configuring &dcache;</title>
      <section id="in-install-configure-terminology">
	<title>Terminology</title>
	  <para>
	    &dcache; consists of one or more <firstterm>domains</firstterm>.
	    A domain in &dcache; is a Java Virtual Machine hosting one or more &dcache;
	    <firstterm>cells</firstterm>. Each domain must have a name which is unique
	    throughout the &dcache; instance and a cell must have a unique name within the
	    domain hosting the cell.
	  </para>
	  <para>
	    A <firstterm>service</firstterm> is an abstraction
	    used in the &dcache; configuration to describe atomic units to add to a
	    domain. It is typically implemented through one or more cells.  &dcache;
	    keeps lists of the domains and the services that are to be run within these
	    domains in the <firstterm>layout files</firstterm>.
	    The layout file may contain domain- and service- specific configuration
	    values. A <firstterm>pool</firstterm> is a cell providing physical data storage
	    services.
	  </para>
	</section>

	<section id="in-install-configure-files">
	  <title>Configuration files</title>

	  <para>
	    In the setup of &dcache;, there are three main places for
	    configuration files:
	    <itemizedlist>
	      <listitem>
		<filename class="directory">&path-ods-usd;/defaults</filename>
	      </listitem>

	      <listitem>
		<filename>&path-ode-ed;/dcache.conf</filename>
	      </listitem>

	      <listitem>
		<filename class="directory">&path-ode-ed;/layouts</filename>
	      </listitem>
	    </itemizedlist>
	    The folder <filename
	    class="directory">&path-ods-usd;/defaults</filename>
	    contains the default settings of the &dcache;.  If one of
	    the default configuration values needs to be changed, copy
	    the default setting of this value from one of the files in
	    <filename
	    class='directory'>&path-ods-usd;/defaults</filename> to
	    the file <filename>&path-ode-ed;/dcache.conf</filename>,
	    which initially is empty and update the value.
	  </para>
	  <note>
	    <para>
	      In this first installation of &dcache; your &dcache;
	      will not be connected to a tape sytem. Therefore please
	      change the values for
	      <literal>pnfsmanager.default-retention-policy</literal> and
	      <literal>pnfsmanager.default-access-latency</literal> in the file
	      <filename>&path-ode-ed;/dcache.conf</filename>.
	    </para>
	    <programlisting>pnfsmanager.default-retention-policy=REPLICA
pnfsmanager.default-access-latency=ONLINE</programlisting>
          </note>

	  <para>
	    Layouts describe which domains to run on a host and which
	    services to run in each domain. For the customized
	    configuration of your &dcache; you will have to create a
	    layout file in <filename
	    class="directory">&path-ode-ed;/layouts</filename>. In
	    this tutorial we will call it the
	    <filename>mylayout.conf</filename> file.
	  </para>
	</section>

	<important>
	  <para>
	    Do not update configuration values in the files in the
	    defaults folder, since changes to these files will be
	    overwritten by updates.
	  </para>
	</important>

	<para>
	  As the files in <filename
	  class="directory">&path-ods-usd;/defaults/</filename> do
	  serve as succinct documentation for all available
	  configuration parameters and their default values it is
	  quite useful to have a look at them.
	</para>

	<section id="in-install-layout">
	  <title>Defining domains and services</title>
	  <para>
	    Domains and services are defined in the layout files.
	    Depending on your site, you may have requirements upon the
	    doors that you want to configure and domains within which
	    you want to organise them.
	  </para>

	  <para>
	    A domain must be defined if services are to run in that
	    domain.  Services will be started in the order in which
	    they are defined.
	  </para>

	  <para>
	    Every domain is a Java Virtual Machine that can be started
	    and stopped separately. You might want to define several
	    domains for the different services depending on the
	    necessity of restarting the services separately.
	  </para>

	  <para>
	    The layout files define which domains to start and which
	    services to put in which domain. Configuration can be done
	    per domain and per service.
	  </para>

	  <para>
	    A name in square brackets, <emphasis>without</emphasis> a
	    forward-slash (<literal>/</literal>) defines a domain.  A
	    name in square brackets <emphasis>with</emphasis> a
	    forward slash defines a service that is to run in a
	    domain.  Lines starting with a hash-symbol
	    (<literal>#</literal>) are comments and will be ignored by
	    &dcache;.
	  </para>

	  <para>
	    There may be several layout files in the layout directory,
	    but only one of them is read by &dcache; when starting
	    up. By default it is the <filename>single.conf</filename>.
	    If the &dcache; should be started with another layout file
	    you will have to make this configuration in
	    <filename>&path-ode-ed;/dcache.conf</filename>.
	  </para>

	  <informalexample>
	    <programlisting>dcache.layout=mylayout</programlisting>
	    This entry in
	    <filename>&path-ode-ed;/dcache.conf</filename> will
	    instruct &dcache; to read the layout file
	    <filename>&path-ode-ed;/layouts/mylayout.conf</filename>
	    when starting up.
	  </informalexample>

	  <informalexample>
	    <para>
	      These are the first lines of
	      <filename>&path-ode-ed;/layouts/single.conf</filename>:
	    </para>
	    <programlisting>dcache.broker.scheme=none

[dCacheDomain]
[dCacheDomain/admin]
[dCacheDomain/broadcast]
[dCacheDomain/poolmanager]</programlisting>

 	    <para>
	      <literal>[&domain-dcache;]</literal> defines a domain
	      called &domain-dcache;. In this example only one domain
	      is defined.  All the services are running in that
	      domain. Therefore no messagebroker is needed, which is
	      the meaning of the entry
	      <literal>messageBroker=none</literal>.
	    </para>

	    <para>
	      <literal>[&domain-dcache;/&cell-admin;]</literal>
	      declares that the &cell-admin; service is to be run in
	      the &domain-dcache; domain.
	    </para>
	  </informalexample>

	  <informalexample>
	    <para>
	      This is an example for the <filename>mylayout.conf</filename> file of a single node
	      &dcache; with several domains.
	    </para>
	    <programlisting>[dCacheDomain]
[dCacheDomain/broadcast]
[dCacheDomain/loginbroker]
[dCacheDomain/topo]
[dCacheDomain/info]

[namespaceDomain]
[namespaceDomain/pnfsmanager]
[namespaceDomain/cleaner]
[namespaceDomain/dir]

[poolmanagerDomain]
[poolmanagerDomain/poolmanager]

[adminDoorDomain]
[adminDoorDomain/admin]

[httpdDomain]
[httpdDomain/httpd]
[httpdDomain/billing]
[httpdDomain/srm-loginbroker]

[gPlazmaDomain]
[gPlazmaDomain/gplazma]</programlisting>
	  </informalexample>

	  <note>
	    <para>
	      If you defined more than one domain, a messagebroker is
	      needed, because the defined domains need to be able to
	      communicate with each other. This means that if you use
	      the file <filename>single.conf</filename> as a template
	      for a &dcache; with more than one domain you need to
	      delete the line
	      <literal>messageBroker=none</literal>. Then the default
	      value will be used which is
	      <literal>messageBroker=cells</literal>, as defined in
	      the defaults
	      <filename>&path-ods-usd;/defaults/dcache.properties</filename>.
	    </para>
	  </note>
	</section>

    <section id="in-install-configure-pools">
      <title>Creating and configuring pools</title>

      <para>
	&dcache; will need to write the files it keeps in pools.
	These pools are defined as services within &dcache;. Hence, they are added
	to the layout file of your &dcache; instance, like all other services.
      </para>
      <para>
      The best way to create a pool, is to use the <literal>dcache</literal> script and restart the domain the pool runs in. The pool will be added to your layout file.
      </para>
      <programlisting>[<replaceable>domainname</replaceable>/pool]
name=<replaceable>poolname</replaceable>
path=/path/to/pool
pool.wait-for-files=${path}/data</programlisting>

	<para>
	  The property <varname>pool.wait-for-files</varname> instructs the
	  pool not to start up until the specified file or directory
	  is available.  This prevents problems should the underlying storage be unavailable (e.g., if a
	  RAID device is offline).
	</para>
    <note>
       <para>
          Please restart &dcache; if your pool is created in a domain that did not exist before.
       </para>
    </note>

      <informalexample>
        <screen>&prompt-root; <userinput>&path-odb-n-s;dcache pool create /srv/dcache/p1 pool1 poolDomain</userinput>
Created a pool in /srv/dcache/p1. The pool was added to poolDomain in
file:/etc/dcache/layouts/mylayout.conf.</screen>
	<para>
	In this example we create a pool called pool1 in the directory <filename class='directory'>/srv/dcache/p1</filename>.
	The created pool will be running in the domain <literal>poolDomain</literal>.
	</para>
      </informalexample>

      <note>
	<title>Mind the Gap!</title>
	<para>
	  The default gap for poolsizes is 4GiB. This means you should
	  make a bigger pool than 4GiB otherwise you would have to
	  change this gap in the &dcache; admin tool. See the example
	  below.  See also <xref linkend="intouch-admin"/>.
	</para>

	<screen>&dc-prompt-local; <userinput>cd <replaceable>poolname</replaceable></userinput>
&dc-prompt-pool; <userinput>set gap 2G</userinput>
&dc-prompt-pool; <userinput>save</userinput></screen>
      </note>

      <para>
	Adding a pool to a configuration does not modify the pool or
	the data in it and can thus safely be undone or repeated.
      </para>

      </section>

      <section id="in-install-configure-starting">
	<title>Starting &dcache;</title>
	<para>
	  Restart &dcache; to start the newly configured components
	  <userinput>&path-odb-n-s;dcache restart</userinput> and
	  check the status of &dcache; with
	  <userinput>&path-odb-n-s;dcache status</userinput>.
	</para>
	<informalexample>
	  <screen>&prompt-root; <userinput>&path-odb-n-s;dcache restart</userinput>
Stopping dCacheDomain 0 1 done
Starting dCacheDomain done
Starting namespaceDomain done
Starting poolmanagerDomain done
Starting adminDoorDomain done
Starting httpdDomain done
Starting gPlazmaDomain done
Starting poolDomain done
&prompt-root; <userinput>&path-odb-n-s;dcache status</userinput>
DOMAIN            STATUS  PID   USER
dCacheDomain      running 17466 dcache
namespaceDomain   running 17522 dcache
poolmanagerDomain running 17575 dcache
adminDoorDomain   running 17625 dcache
httpdDomain       running 17682 dcache
gPlazmaDomain     running 17744 dcache
poolDomain        running 17798 dcache</screen>
	</informalexample>
      </section>

      <para>
	Now you can have a look at your &dcache; via The Web
	Interface, see <xref linkend="intouch-web">intouch-web</xref>:
	<uri>http://<replaceable>httpd.example.org</replaceable>:2288/</uri>,
	where <replaceable>httpd.example.org</replaceable> is the node on which your
	&cell-httpd; service is running.
	For a single node &dcache; this is the machine on which your &dcache; is running.
      </para>


      <section id="in-install-configure-java">
	<title>&java; heap size</title>

      <para>
	By default the &java; heap size and the maximum direct buffer
	size are defined as
	</para>
	<programlisting>dcache.java.memory.heap=512m
dcache.java.memory.direct=512m</programlisting>
	<para>
        Again, these values can be changed in
	<filename>&path-ode-ed;/dcache.conf</filename>.
      </para>

	<para>
	  For optimization of your &dcache; you can define the &java; heap size in the
	  layout file separately for every domain.
	  <informalexample>
	    <programlisting>[dCacheDomain]
dcache.java.memory.heap=2048m
dcache.java.memory.direct=0m
...
[utilityDomain]
dcache.java.memory.heap=384m
dcache.java.memory.direct=16m</programlisting>
	  </informalexample>
	</para>

      <note>
        <para>
	  &dcache; uses &java; to parse the configuration files and
	  will search for &java; on the system path first; if it is
	  found there, no further action is needed. If &java; is not
	  on the system path, the environment variable
	  <envar>JAVA_HOME</envar> defines the location of the &java;
	  installation directory. Alternatively, the environment
	  variable <envar>JAVA</envar> can be used to point to the
	  &java; executable directly.
        </para>

	<para>
	  If <envar>JAVA_HOME</envar> or <envar>JAVA</envar> cannot be
	  defined as global environment variables in the operating
	  system, then they can be defined in either
	  <filename>/etc/default/dcache</filename> or
	  <filename>/etc/dcache.env</filename>.  These two files are
	  sourced by the init script and allow
	  <envar>JAVA_HOME</envar>, <envar>JAVA</envar> and
	  <envar>DCACHE_HOME</envar> to be defined.
	</para>
      </note>

      </section>

  </section>

  <section id="in-install-multinode">
    <title>Installing &dcache; on several nodes</title>

    <para>
      Installing &dcache; on several nodes is not much more
      complicated than installing it on a single node.  Think about
      how &dcache; should be organised regarding services and
      domains. Then adapt the layout files, as described in <xref
      linkend="in-install-layout" />, to the layout that you have in
      mind. The files
      <filename>&path-ode-ed;/layouts/head.conf</filename> and
      <filename>&path-ode-ed;/layouts/pool.conf</filename> contain
      examples for a &dcache; head-node and a &dcache; pool
      respectively.
    </para>

    <important>
      <para>
	You must configure a domain called &domain-dcache; but the
	other domain names can be chosen freely.
      </para>
      <para>
	Please make sure that the domain names that you choose are
	unique. Having the same domain names in different layout files
	on different nodes may result in an error.
      </para>
    </important>

    <para>
      On any other nodes than the head node, the property <varname>dcache.broker.host</varname>
      has to be added to the file <filename>&path-ode-ed;/dcache.conf</filename>. This property
      should point to the host containing the special domain &domain-dcache;, because that domain acts implicitly as a broker.
    </para>

    <tip>
      <para>
	On &dcache; nodes running only pool services you do not need to
	install &psql;. If your current node hosts only these services,
	the installation of &psql; can be skipped.
      </para>
    </tip>

  </section>

</section>

<section id="in-upgrade">
  <title>Upgrading a &dcache; Instance</title>
    <important>
      <para>
	Always read the release notes carefully before upgrading!
      </para>
    </important>
  <para>
    Upgrading to bugfix releases within one supported branch (e.g. from
    &dcache-patch-version; to  &dcache-next-patch-version;) may be done by
    upgrading the packages with
  </para>
    <screen>&prompt-root; <userinput>rpm -Uvh <replaceable>packageName</replaceable></userinput></screen> 
    <para>
      Now &dcache; needs to be started again.
    </para>
    <para>
      For major upgrades please
    </para>
    <itemizedlist>
      <listitem>
	use <ulink url='http://www.dcache.org/manuals/2011/goettingen/upgradeguide/upgrade-guide.html'>The Ultimate Golden Release Upgrade Guide I</ulink> to upgrade from 1.9.5 to 1.9.12.
      </listitem>
      <listitem>
	use the <ulink url='http://www.dcache.org/manuals/upgrade-1.9.12-to-2.2.shtml'>The Ultimate Golden Release Upgrade Guide II</ulink> to upgrade from 1.9.12 to 2.2.
      </listitem>
      <listitem>
	use the <ulink url='http://www.dcache.org/manuals/upgrade/upgrade-2.2-to-2.6.html'>The Ultimate Golden Release Upgrade Guide III</ulink> to upgrade from 2.2 to 2.6. 
      </listitem>
      <listitem>
	use the <ulink url='http://trac.dcache.org/wiki/optToUsr'>/opt
	to /usr</ulink> migration guide to migrate from the /opt
	layout to the fhs-compliant layout.
      </listitem>
    </itemizedlist>
</section>

</chapter>