Added maintenance information and started preparation for 2.1 release
authorAnders Henja <anders@henjab.se>
Fri, 12 Dec 2014 17:18:06 +0000 (18:18 +0100)
committerAnders Henja <anders@henjab.se>
Fri, 12 Dec 2014 17:18:06 +0000 (18:18 +0100)
17 files changed:
Makefile
doc/config.dox
doc/distr.dox
doc/faq.dox
doc/help.dox
doc/install.dox
doc/intro.dox
doc/maintenance.dox [new file with mode: 0644]
doc/pgf.dox
doc/reqs.dox
doc/secure.dox
doc/subscribe.dox
doc/ug.dox
images/delivery_registry.png [new file with mode: 0644]
images/message_settings.png [new file with mode: 0644]
images/trim_by_count.png [new file with mode: 0644]
images/trim_by_count_schedule.png [new file with mode: 0644]

index 44832e2..ed23dbc 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -8,11 +8,11 @@
 ################################################################################
 all:
 
-.PHONY=doc
+.PHONY: doc
 doc:
        @doxygen doxygen.cfg
 
-.PHONY=clean
+.PHONY: clean
 clean:
        @\rm -rf doxygen/*
        @\rm -f doc/*~
@@ -21,7 +21,7 @@ clean:
        @\rm -f images/*~
        @\rm -f *~
 
-.PHONY=distclean
+.PHONY: distclean
 distclean:
        @\rm -rf doxygen/*
        @\rm -f doc/*~
index 90468bd..0c84956 100644 (file)
@@ -1,6 +1,6 @@
 /** \page config Configuration
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 Congratulations! If you've come this far, it means you've succesfully
 followed the instructions in \ref install and you have a node that is up and
index 9675164..61f315b 100644 (file)
@@ -1,6 +1,6 @@
 /** \page dist Distribution
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 We've installed and configured a BALTRAD node, injected our own data into
 it, exchanged data with other nodes, generated products with all the data,
index ca3c116..1e33d2f 100644 (file)
@@ -1,6 +1,6 @@
 /** \page faq Frequently Asked Questions
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 \htmlonly<hr>\endhtmlonly
 
index 1ee1997..cd8c5f8 100644 (file)
@@ -1,6 +1,6 @@
 /** \page help Getting post-installation help
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 The various subsystems' built-in documentation will be generated
 automatically during \ref install. This is detailed technical documentation
index 4a93941..bf32957 100644 (file)
@@ -1,6 +1,6 @@
 /** \page install Installation
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 Welcome to the installation chapter of the user guide. BALTRAD software has
 been built and installed in seven countries already, and at least three
@@ -281,13 +281,14 @@ Options:
     this option. It will try to restore the configuration parameters
     used in the last run. 
 
---nodename
+--nodename=<name>
     This attribute should really be specified but there is a default value which
-    is the hostname as shown by the command 'hostname'. The node name is a unique
-    identifier that is used for identifying you within the exchange
+    is the hostname as shown by the command 'hostname'. The node name is a 
+    unique identifier that is used for identifying you within the exchange
     network. The node name should usually explain exactly who you are. A good
-    example is to use the java package naming. For example se.myorg or se.myorg.test or similar. 
-    This node name will also defining what this installations key will be named.
+    example is to use the Java package naming. For example se.myorg or 
+    se.myorg.test or similar. This node name will also defining what this 
+    installations key will be named.
 
 --prefix=<prefix>
     Points out where the system should be installed. 
@@ -304,7 +305,7 @@ Options:
 --keystore=<path>
     Point out the keystore directory to use when configuring setting up the
     different modules for certification. If not specified, one will be
-    created for you in /opt/baltrad/etc/bltnode-keystore.
+    created for you in <prefix>/etc/bltnode-keystore.
 
 --with-zlib=yes|no|<zlibroot>|<zlibinc>,<zliblib>
     Specifies if zlib should be built by the installer or not. 
@@ -328,8 +329,8 @@ Options:
       include and library paths
 
 --with-freetype=<freetypeinc>,<freetypelib>
-    In order to get freetype support built in the PIL imaging library
-    (for use with Google Maps Plugin). You might have to specify this
+    In order to get freetype support built in the Python Imaging Library (PIL,
+    for use with Google maps plugin). You might have to specify this
     library. <freetypeinc> is the path to the freetype include directory
     as shown when executing freetype-config --cflags excluding the -I of course.
     <freetypelib> is the path where libfreetype.so can be found.
@@ -351,7 +352,7 @@ Options:
     [Default 127.0.0.1]
 
 --with-hdfjava=<hdf java root>
-    Specifies the hdf java root installation directory. 
+    Specifies the HDF Java root installation directory. 
     If omitted, the installer will install it's own version of hdf-java.
     
 --reinstalldb
@@ -363,99 +364,108 @@ Options:
     to be set as installed.
     
 --runas=<user>
-    Specifies the runas user for tomcat and other processes. It is not 
-    allowed to use a runas user that is root due to security-issues. 
+    Specifies the runas user for Tomcat and other processes. It is not 
+    allowed to use a runas user that is root due to security issues. 
     [Defaults to user that is installing]
 
 --datadir=<dir>
-    The directory where all the data storage files should be placed for baltrad-db.
+    The directory where all the data storage files should be placed for 
+    BALTRAD-db.
     [Default <prefix>/bdb_storage]
 
 --urlrepo=<url>
-    The url from where the url packages can be fetched.
+    The URL from where the dependency packages can be fetched.
     [Default http://git.baltrad.eu/blt_dependencies]
     
 --gitrepo=<url>
-    The url from where the baltrad node git packages can be fetched.
-    [Default gitosis@git.baltrad.eu]
+    The URL from which the BALTRAD node Git packages can be fetched.
+    For example --gitrepo=http://git.baltrad.eu
+    [Default git://git.baltrad.eu]
 
 --with-rave
-    Install the rave pgf
+    Install the RAVE PGF
 
 --rave-pgf-port=<port>
-    Set the port rave should run on.
+    Set the port RAVE should run on.
     [default: 8085]
 
+--rave-log-port=<port>
+    Set the port the RAVE logger should run on.
+    [default: 8089]
+
 --with-bufr
-    Install the bufr software. This will also affect rave so that if
-    we have specified bufr support rave will be built with bufr support
-    enabled as well.
+    Install OPERA BUFR software. This will affect RAVE such that readling of
+    polar data in BUFR will be supported.
 
 --rave-center-id=<id>
-    Originating center id to be used by rave as the source of its products.
+    WMO originating center ID to be used by RAVE as the source of its products.
+    Reference: WMO No. 306.
     [default: 82]
 
 --rave-dex-spoe=<spoe>
-    Dex's single point of entry to be used by rave. 
-    [default: localhost:
+    DEX's single point of entry to be used by RAVE. 
+    [default: localhost:8080]
     
 --with-rave-gmap
-    Install the rave google map plugin. Will also cause rave pgf to be installed.
+    Install the RAVE Google map plugin. Will also cause RAVE PGF to be 
+    installed.
 
 --with-bropo
-    Install the anomaly detector bropo. Will also cause rave to be installed.
-
---with-beamb
-    Install the beam blockage detector beamb. Will also cause rave to be installed.
+    Install bRopo anomaly detectors. Will also cause RAVE to be installed.
 
 --with-beamb
-    Install the beam blockage detector beamb. Will also cause rave to be installed.
+    Install beam blockage detector package. Will also cause RAVE to be 
+    installed.
 
 --with-bwrwp
-    Installs the baltrad weather radar wind profile generator. Will also cause rave to be installed.
-    This is a very special product generator that uses fortran code and requires for example gfortran.
-    This product more or less requires that the following options also are specified: --with-blas=,
-    --with-cblas=, --with-lapack= and --with-lapacke=.
+    Installs the BALTRAD weather radar wind profile generator. Will also cause 
+    RAVE to be installed. This is a very special product generator that 
+    requires a Fortran compiler to built its dependencies, e.g. gfortran.
+    This product requires that the following options also are specified: 
+    --with-blas=, --with-cblas=, --with-lapack= and --with-lapacke=. 
+    See below on how to use these options.
  
 --with-blas=<libblas.a directory>
-    Specifies the directory where the libblas.a library resides. Currently only used when installing bwrwp.
-    NOTE that the library objects must have been compiled with -fPIC or similar for shared object capabilities
-    since it will be linked into a shared library.
+    Specifies the directory where the libblas.a library resides. Currently only 
+    used when installing bwrwp.
+    NOTE that the library objects must have been compiled with -fPIC or similar 
+    for shared object capabilities since it will be linked into a shared 
+    library.
 
 --with-cblas=<root> or <cblas.h incdir>,<libcblas.a dir>
-    Specifies where the cblas.h include directory and the libcblas.a directory resides. You can also
-    specify cblas root directory that should contain the include and lib directory.
-    Currently only used when installing bwrwp.
-    NOTE that the library objects must have been compiled with -fPIC or similar for shared object capabilities
-    since it will be linked into a shared library.
+    Specifies where the cblas.h include directory and the libcblas.a directory 
+    resides. You can also specify CBLAS root directory that should contain the 
+    include and lib directory. Currently only used when installing bwrwp.
+    NOTE that the library objects must have been compiled with -fPIC or similar 
+    for shared object capabilities since it will be linked into a shared 
+    library.
 
 --with-lapack=<liblapack.a directory>
-    Specifies the directory where the liblapack.a library resides. Currently only used when installing bwrwp.
-    NOTE that the library objects must have been compiled with -fPIC or similar for shared object capabilities
-    since it will be linked into a shared library.
-
---with-lapacke=<root> or <lapacke.h incdir>,<liblapacke.a dir>
-    Specifies where the cblas.h include directory and the libcblas.a directory resides. You can also
-    specify cblas root directory that should contain the include and lib directory.
-    Currently only used when installing bwrwp.
-    NOTE that the library objects must have been compiled with -fPIC or similar for shared object capabilities
-    since it will be linked into a shared library.
-
---with-bdbfs
-    Will build and install the baltrad db file system driver
+    Specifies the directory where the liblapack.a library resides. Currently 
+    only used when installing bwrwp. NOTE that the library objects must have 
+    been compiled with -fPIC or similar for shared object capabilities since it 
+    will be linked into a shared library.
+
+--with-lapacke=<lapacke.h incdir>,<liblapacke.a dir>
+    Specifies where the cblas.h include directory and the libcblas.a directory 
+    resides. Currently only used when installing bwrwp.
+    NOTE that the library objects must have been compiled with -fPIC or similar 
+    for shared object capabilities since it will be linked into a shared 
+    library.
 
 --bdb-port=8090
     BDB server port
 
 --bdb-uri=<uri>
-    The BDB uri, as default this has no use even when specified. It will only be used
-    if subsystems has been specified so that you can specify a different BDB server. Also,
-    if this is specified, bdb-port will not have any meaning.
+    The BDB URI, as default this has no use even when specified. It will only 
+    be used if subsystems have been specified so that you can specify a 
+    different BDB server. Also, if this is specified, bdb-port will not have 
+    any meaning.
     E.g. --bdb-uri=http://somehost:8090
     [Default: Not used]
 
 --bdb-pool-max-size=<N>
-    Set the pool size for bdb connections to <N>
+    Set the pool size for BDB connections to <N>
     [default: 10]
 
 --bdb-auth=<authtype>
@@ -482,56 +492,65 @@ Options:
     Prints the build configuration
     
 --exclude-tomcat
-    Will exclude installation of tomcat. This is not a recommended procedure but 
-    it is here for the possibility to use your own tomcat installation if it 
-    is necessary.
+    Will exclude installation of Tomcat. This is not a recommended procedure 
+    but it is here for the possibility to use your own Tomcat installation if 
+    necessary.
 
 --tomcatport=<port>
-    Specifies the port on which the tomcat installation should listen on.
+    Specifies the port on which the Tomcat installation should listen.
     Don't use together with --tomcaturl. 
     [Default 8080]
 
 --keystoredn=<dn>
-    The distinguished name used in the keystore cert for the secure communication.
-    If <dn> is yes, then a number of questions will be asked during the creation of the keystore.
-    If <dn> is no, then a predefined dn will be created with the format
+    The distinguished name used in the keystore cert for the secure 
+    communication. If <dn> is yes, then a number of questions will be asked 
+    during the creation of the keystore. If <dn> is no, then a predefined DN 
+    will be created with the format
       "CN=Unknown,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown"
-    Or you can specify your own DN, just keep the above format. Note, that you can not specify a dn with any
-    spaces in it. If you have that format you will have to use 'yes' instead to get the questions
+    Or you can specify your own DN, just keep the above format. Note, that you 
+    cannot specify a DN with any spaces in it. If you have that format you will 
+    have to use 'yes' instead to get the questions.
     [Default yes]
-
+    
 --keystorepwd=<pwd>
-    Specifies the password that should be used for the key. If this has not been defined, the tomcatpwd will be used.
+    Specifies the password that should be used for the key. If this has not been
+    defined, the tomcatpwd will be used.
 
 --tomcatsecureport=<port>
-    Specifies the port on which the tomcat installation should listen on for secure messages.
+    Specifies the port on which the Tomcat installation should listen on for 
+    secure messages.
     [Default 8443]
 
 --tomcaturl=<url>
-    Specifies the tomcat url where the tomcat installation resides. Don't
-    use together with --tomcatport. 
+    Specifies the URL where the Tomcat installation resides. Don't use together 
+    with --tomcatport. 
     [Default http://localhost:8080]
     
 --tomcatpwd=<pwd>
     Specifies the password that should be used for the manager in the tomcat
     installation.
+
+--tomcatfwdports=<httpport>,<httpsport>
+    Specifies that port forwarding has to be supported by the node and hence a secondary mapping
+    is added to the dex applicationContext. This attribute is typically used when having the tomcat
+    server behind a firewall and proxying calls through a webserver like apache.
     
 --force
     Unused at the moment
     
 --experimental
-    When running into problems with building, like missing libraries, link problems
-    or other miscellaneous problems. This might be the option to specify. Some modules
-    are currently beeing evaluated if they are stable enough to be used in production
-    and by specifying this option these modules will be built instead.
-
---subsystems=(STANDALONE_RAVE, RAVE ,BDB ,DEX)
-    If you are interested in running a standalone installation of RAVE, BDB or DEX. It
-    is possible to do so by specifying which subsystems that should be installed.
-    Since RAVE is depending on the BALTRAD-DB python client API you are able to specify
-    a specific RAVE module called STANDALONE_RAVE which installs RAVE without any
-    BDB-dependencies.    
+    When running into problems with building, like missing libraries, link 
+    problems or other miscellaneous problems, this might be the option to 
+    specify to get through the build. Some modules are currently being 
+    evaluated for stability in a production environment, and by specifying this 
+    option, these modules will be built instead.
     
+--subsystems=(STANDALONE_RAVE, RAVE ,BDB ,DEX)
+    If you are interested in running a standalone installation of RAVE, BDB or 
+    DEX, it is possible to do so by specifying which subsystems that should be 
+    installed. Since RAVE depends on the BALTRAD-DB Python client API, you are 
+    able to specify a specific RAVE module called STANDALONE_RAVE which installs
+    RAVE without any BDB-dependencies.       
 \endverbatim
 
  */
index a67207e..4a531ed 100644 (file)
@@ -1,8 +1,8 @@
 /** \mainpage Community-based weather radar networking
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 \par Copyright 
-&copy; 2013 Swedish Meteorological and Hydrological Institute (SMHI), Norrk&ouml;ping, Sweden <br> on behalf of the BALTRAD partnership
+&copy; 2014 Swedish Meteorological and Hydrological Institute (SMHI), Norrk&ouml;ping, Sweden <br> on behalf of the BALTRAD partnership
 
 \par Legals
 BALTRAD is free software: you can redistribute it and/or modify
@@ -45,9 +45,17 @@ TAKE ME TO ...
 \htmlonly
 <table border="0">
 <tr>
-<td><img src="EU_logo.jpg"</td>
+<td>
+\endhtmlonly
+\image html EU_logo.jpg
+\htmlonly
+</td>
 <td><center>Part-financed by the European Union (European Regional Development Fund and European Neighbourhood and Partnership Instrument)</center></td>
-<td><a href="http://eu.baltic.net/" target="_blank"><img src="BSR-logo.png" /></a></td>
+<td><a href="http://eu.baltic.net/" target="_blank">
+\endhtmlonly
+\image html BSR-logo.png
+\htmlonly
+</a></td>
 </tr>
 </table>
 \endhtmlonly
diff --git a/doc/maintenance.dox b/doc/maintenance.dox
new file mode 100644 (file)
index 0000000..88be04e
--- /dev/null
@@ -0,0 +1,82 @@
+/** \page maintenance Maintenance
+\date December 2014
+\version 2.1
+
+There are so many different ways to maintain a computer system so we will just focus on some 
+specific parts related to the baltrad software. Other than that, you will have to refer to
+other documentation or your sysadmin for more tips and tricks.
+
+\section maintenance_database Database maintenance
+In a real time system like baltrad you will most likely have a heavy flow of data coming into
+the system, filling and fragmenting the database. In order to have a stable system you will have
+to configure and activate a number of these.
+
+\subsection maintenance_delivery_registry Delivery registry
+The delivery registry is the DEX's way of keeping track of the files that has arrived into the system. 
+To ensure that this registry does not grow out of control you will have to activate this feature.
+Navigate to "settings->Delivery registry->Configure" and you will see the following view.
+
+\image html delivery_registry.png
+
+You should select one of these options in order to keep the delivery registry under control. 
+
+\subsection maintenance_message_settings Message settings
+In the same way as for the delivery registry, the system messages must be kept down to a reasonable
+level. Navigate to "settings->Messages->Configure" and you will see the following view.
+
+\image html message_settings.png
+
+
+Now you have configured so that DEX does not grow out of control, time to take care of the baltrad db.
+
+\subsection maintenance_bdb_rules Baltrad DB rules
+
+It is even more important that baltrad-db is keept under control since all data is stored in the database.
+The baltrad db is handled by a couple of beast rules, "DB trim count" and "DB trim age" rule. The rules in them
+self are very easy. Either you configure so that the number of files are kept below a certain level (trim count)
+or all files older than x seconds (trim age).
+
+Below is an example on how the trim by count rule can look like with values set which can be found by navigating
+to "processing->Routes->Create DB trim count" 
+
+\image html trim_by_count.png
+
+The rules are not autmatically run, instead you have to configure the scheduler to execute the rule which can be
+found in "processing->Schedule" and then pressing Create. Depending on the load and number of incoming files you
+might have to run the scheduler often but this might cause consequences on your data processing like gra and acrr 
+if you don't allow at least a couple of days of data in the rule. If you want to configure the schedule so that it
+is run once an hour every day, then it will look like
+
+\image html trim_by_count_schedule.png
+
+\subsection maintenance_psql Postgresql database
+
+Usually this step is something that most admins have got a clear idea on how to do or there already are procedures
+to keep the postgresql database fresh. However, some pointers might come in handy when maintaining the database.
+
+The first thing to be aware of with the baltrad software is that there will be a lot of fragmentation of the database due
+to all the creation and deletion of data within the database. Since the files as default also is stored as large objects
+within the database, the fragmentation will be even worse. This can quite easilly be managed as long as you are aware of it.
+
+The first thing to do is to activate autovacuum in the postgres database. Locate the postgresql.conf file, usually it is
+placed in something like "/var/lib/pgsql/data/postgresql.conf" or "/etc/postgresql/.../postgresql.conf". Edit the file and
+locate the entry "#autovacuum = on" and remove the comment so that it is activated. Then restart the database.
+
+Unfortunately, this might not be enough to keep the database in shape so you will have to create a crontab job as well
+that performs another vacuum.
+
+As user postgres, create a script (e.g. /var/lib/pgsql/vacuum_cron.sh) that contains the following
+\verbatim
+#!/bin/sh
+psql baltrad <<EOF > /tmp/vacuum.txt 2>&1
+vacuum analyze verbose;
+EOF
+\endverbatim
+
+Then create a crontab job as user postgres that executes the above mentioned vacuum script. The below example is run 2 times a week.
+\verbatim
+0 23 * * 2,6 /var/lib/pgsql/vacuum_cron.sh
+\endverbatim
+
+
+ */
\ No newline at end of file
index 00914d3..acad29a 100644 (file)
@@ -1,6 +1,6 @@
 /** \page pgf Processing data
-\date January 2012
-\version 1.0
+\date December 2014
+\version 2.1
 
 Your node should now be receiving data from your own radar(s), and
 exchanging data safely and smoothly with other nodes. This is where you can
index 856ab2d..03b02ea 100644 (file)
@@ -1,5 +1,5 @@
 /** \page req Requirements
-\date October 2013
+\date December 2014
 \version 1.1
 
 \li \ref req_hw
index bfe6d9d..e8d7ad4 100644 (file)
@@ -1,6 +1,6 @@
 /** \page secure Security in BALTRAD
-\date October 2013
-\version 1.1
+\date October 2014
+\version 2.1
 
 The BALTRAD system communicates with other nodes securely, and the
 web-based user interface is also secure - sensitive data is encrypted before
index b860208..4fc3772 100644 (file)
@@ -1,6 +1,6 @@
 /** \page subscribe Exchanging data
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 In BALTRAD, you control \b who is allowed access to \b what. We recognize
 that we live in an international world where we benefit from exchanging
index d6d0222..f939283 100644 (file)
@@ -1,6 +1,6 @@
 /** \page ug User Guide
-\date October 2013
-\version 1.1
+\date December 2014
+\version 2.1
 
 Welcome to the BALTRAD User Guide. This documentation is designed
 to assist you with the most common tasks you undertake with BALTRAD
@@ -36,5 +36,7 @@ some necessary overall context.
 
 \ref dist
 
+\ref maintenance
+
 
  */
diff --git a/images/delivery_registry.png b/images/delivery_registry.png
new file mode 100644 (file)
index 0000000..e09f52d
Binary files /dev/null and b/images/delivery_registry.png differ
diff --git a/images/message_settings.png b/images/message_settings.png
new file mode 100644 (file)
index 0000000..681a17d
Binary files /dev/null and b/images/message_settings.png differ
diff --git a/images/trim_by_count.png b/images/trim_by_count.png
new file mode 100644 (file)
index 0000000..a5d70f6
Binary files /dev/null and b/images/trim_by_count.png differ
diff --git a/images/trim_by_count_schedule.png b/images/trim_by_count_schedule.png
new file mode 100644 (file)
index 0000000..9efae75
Binary files /dev/null and b/images/trim_by_count_schedule.png differ