Hyrax: BES Administrative Commands

BES Administration Commands

Namespace: http://xml.opendap.org/ns/bes/admin/1.0#

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:Stop />
 </hai:BesAdminCmd>

StopNow

Example:

<hai:StopNow/>

Stops all beslistener processes; does not wait for current transmissions to complete

Request Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:StopNow/>
 </hai:BesAdminCmd>

Response Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:OK/>
 </hai:BesAdminCmd>

<?xml version="1.0" encoding="UTF-8"?>
 <hai:ParseError xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     message text
 </hai:ParseError>

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BESError xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     message text
 </hai:BESError>

---

GetConfig

Example:

<hai:GetConfig />

Retrieves the BES configuration file.

Request Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:GetConfig />
 </hai:BesAdminCmd>

Response Example

<hai:BesConfig>
   #-----------------------OPeNDAP BES Initialization file-----------------#
   #                                                                       #
   #       National Center for Atmospheric Research (NCAR)                 #
   #       High Altitude Observatory (HAO)	                                #
   #       Key entries for OPeNDAP BES run time behavior                   #
   #                                                                       #
   #-----------------------------------------------------------------------#
     
   #-----------------------------------------------------------------------#
   # Who is the administrator for this OPeNDAP back-end server             #
   # Please replace this with the email address to use that gets displayed #
   # to users of your server when errors occur.                            #
   #-----------------------------------------------------------------------#
   BES.ServerAdministrator=admin.email.address@your.domain.name
   
   #-----------------------------------------------------------------------#
   # User and Group to run the BES as					#
   #-----------------------------------------------------------------------#
   # Notes:
   # 1. The user_name and group_name can be user and group ids. To use
   # a user or group id specify the id with the '#' character in front.
   # For example:
   # BES.User=#172
   # BES.Group=#14
   BES.User=user_name
   BES.Group=group_name
   
   #-----------------------------------------------------------------------#
   # Where we log the stuff...and how much we log                          #
   #-----------------------------------------------------------------------#
   BES.LogName=/usr/local/opendap/servers/hyrax-1.8.0/var/bes.log
   BES.LogVerbose=no
   
   #-----------------------------------------------------------------------#
   # Setting data information
   #-----------------------------------------------------------------------#
   
   # There are two ways the BES can be used. It can serve as a standalone
   # data server or it can work with the OLFS (i.e., as one component of
   # the OPeNDAP 4 Data Server Hyrax). How you point to data differs for
   # each of the two cases. Most users will be using the BES with the OLFS
   # as part of the OPeNDAP 4 Data Server Hyrax. In this case, set the
   # parameter below, BES.Catalog.catalog.RootDirectory, to point to the
   # root directory that contains the data you want to serve. In this case
   # the value of the 'BES.Data.RootDirectory' parameter, set below to
   # /dev/null, doesn't matter, so long as it has some value.
   
   BES.Catalog.catalog.RootDirectory=/Users/ndp/OPeNDAP/Projects/Hyrax/SVNDataProject
   
   #-----------------------------------------------------------------------#
   # NOTE: It is unlikely that you will need to change anything under      #
   #       this comment.                                                   #
   #-----------------------------------------------------------------------#
   
   #-----------------------------------------------------------------------#
   # modules to load, includes data modules and command modules            #
   #-----------------------------------------------------------------------#
   
   # Notes:
   # 1. All module configuration files will be located under
   # <prefix>/etc/bes/modules. No modules are loaded in this configuration
   # file. The module configuration files are included at the very bottom
   # of this file. And the module configuration files add to this
   # parameter.
   #
   BES.modules=
   
   #-----------------------------------------------------------------------#
   # Setting the data location
   #-----------------------------------------------------------------------#
   
   # If you intend to use the BES as a standalone server, set the value of
   # 'BES.Data.RootDirectory' to point to your data and disregard the 
   # 'BES.Catalog.catalog.RootDirectory' parameter in dap.conf.
   #
   # The default value of RootDirectory is /dev/null, which means that
   # BES.Data.RootDirectory is not used and BES.Catalog.catalog.RootDirectory
   # is used from dap.conf. If you want to use this parameter instead, set
   # it to <prefix>/share/hyrax, where prefix is the installation directory
   # for the BES. This will work with the sample data we include with
   # various format handlers distributed for use with the BES. Or you'll need
   # to change this to point to your data! At this time the BES does not
   # support multiple RootDirectory values.
   
   BES.Data.RootDirectory=/dev/null
   
   # Is the BES allowed to follow symbolic links when requesting catalog
   # information. The default is to not allow the BES to follow symbolic links.
   # The values can be either No or Yes. If set to No, and the user requests
   # catalog information on a symbolic link then an error is reported and if a
   # symbolic link is contained within a collection, it is not included in the
   # response. If set to Yes then the requested node in the catalog is treated
   # like any other node.
   #
   # BES.FollowSymLinks parameter is for non-catalog containers and is used in
   # conjunction with the BES.RootDirectory above. It is NOT a general setting.
   
   BES.FollowSymLinks=No
   
   #-----------------------------------------------------------------------#
   # connection information, unix socket, port number, and whether server  #
   # is secure or not. If you are using this option, make sure the BES is  #
   # behind a firewall which blocks the BES.ServerPort unless you intend   #
   # to provide direct access to the BES for the world. In general, if     #
   # that is the case, you should configure the BES to use SSL.            #
   #-----------------------------------------------------------------------#
   BES.ServerPort=10002
   # BES.ServerUnixSocket=/tmp/bes.socket
   
   #-----------------------------------------------------------------------#
   # To communicate with the besdaemon, use the port or unix socket given  #
   # below. If one of these values is not given, then the command interface#
   # will not be available (and the daemon will not listen on the port or  #
   # socket. If you do use the interface, make sure to protect it from     #
   # outside access using a firewall. Please re-read that last sentence.   #
   #-----------------------------------------------------------------------#
   
   BES.DaemonPort=11002
   
   #-----------------------------------------------------------------------#
   # Security information for this server. ServerSecure specifies whether  #
   # the server is secure or not and requires authentication of the client #
   # using SSL certificates and keys. The default secure connection port   #
   # is 10003. Then specify the full path to the certificate and key files.#
   # An initialization file can be created for both the client and server  #
   # side.                                                                 #
   #-----------------------------------------------------------------------#
   BES.ServerSecure=no
   BES.ServerSecurePort=10003
   BES.ServerCertFile=/full/path/to/serverside/certificate/file.pem
   BES.ServerCertAuthFile=/full/path/to/serverside/certificate/authority/file.pem
   BES.ServerKeyFile=/full/path/to/serverside/key/file.pem
   BES.ClientCertFile=/full/path/to/clientside/certificate/file.pem
   BES.ClientCertAuthFile=/full/path/to/clientside/certificate/authority/file.pem
   BES.ClientKeyFile=/full/path/to/clientside/key/file.pem
   
   #-----------------------------------------------------------------------#
   # help file locations, for text, html, and xml versions                 #
   #-----------------------------------------------------------------------#
   BES.Help.TXT=/usr/local/opendap/servers/hyrax-1.8.0/share/bes/bes_help.txt
   BES.Help.HTML=/usr/local/opendap/servers/hyrax-1.8.0/share/bes/bes_help.html
   BES.Help.XML=/usr/local/opendap/servers/hyrax-1.8.0/share/bes/bes_help.xml
   
   #-----------------------------------------------------------------------#
   # Should informational response objects be buffered, or streamed        #
   # Should informational objects be formatted as text, html, or xml       #
   #-----------------------------------------------------------------------#
   BES.Info.Buffered=no
   BES.Info.Type=xml
   
   #-----------------------------------------------------------------------#
   # Cache and compression configuration                                   #
   #                                                                       #
   # If a data file is compressed the BES will attempt to uncompress it.   #
   #                                                                       #
   #-----------------------------------------------------------------------#
   
   # Currently the bz2 and gz file compression methods are understood by the
   # BES. We will add support for Z (Unix compress) if there's demand for it.
   
   # All of the following five parameters must be set in this file.
   
   # BES.CacheDir: Where should the result of decompressing a file be stored?
   # We've set the value to '/tmp' but you might want to change that to
   # /tmp/bes, /var/cache/bes, et c., depending on the server-host's
   # organization.
   
   # BES.CachePrefix: Prefix for the name of the file used to store the result
   # of decompression.
   
   # BES.CacheSize: Size of the cache in megabytes. When the size of the cached
   # files exceeds this value, the cache will be purged using a
   # last-accessed-first-removed approach. Because it's usually impossible to
   # determine the sizes of data files before decompressing them, there may be
   # times when the cache holds more data than this value. Ideally this value
   # should be several times the size of the largest file you plan to serve. 
   
   # BES.Uncompress.Retry: When waiting for the cache lock, how long should the
   # BES wait before trying to get the lock again if previous attempts have
   # failed? 
   
   # BES.Uncompress.NumTries: How many times should the BES try to acquire the
   # lock before it signals an error?
   
   # The BES cache directory is locked to prevent the different beslistener
   # processes from simultaneously removing files and leaving the cache in an
   # inconsistent state. Use the Retry and NumTries parameters to tune this
   # behavior. Generally, NumTries should be set to about 10. The units of Retry
   # are microseconds. To tune the NumTries and Retry, use the formula Retry =
   # (0.2s/Average_file_sizeMB)/NumTries. So if your average file size is 10MB
   # and you've settled on a NumTries of 10, (0.2s/10MB)/10 = 0.002s or 2000
   # microseconds. If you have really large files (e.g., decompressed they are
   # 500MB), try setting NumTries to 100.
   
   BES.CacheDir=/tmp
   BES.CachePrefix=bes_cache
   BES.CacheSize=500
   BES.Uncompress.Retry=2000
   BES.Uncompress.NumTries=10
   
   #-----------------------------------------------------------------------#
   # If the symbolic name cannot be found in persistence, nice means simply#
   # log an error, strict means throw an exception                         #
   #-----------------------------------------------------------------------#
   BES.Container.Persistence=strict
   
   #-----------------------------------------------------------------------#
   # Defines the TCP buffer size to use in sending and receiving data in   #
   # the BES. With these parameters you will be able to maximize the       #
   # TCP capacity of the client and server communication by setting the	#
   # size of the internal BES buffers to match that of your systems TCP	#
   # window sizes. System administratos can tune the TCP window sizes in	#
   # the kernal. If this is done, set these parameters to match those	#
   # buffer sizes set in the kernel. Or, if your system supports dynamic	#
   # TCP window sizes, as many are doing these days, then leave the	#
   # SetSock*Size parameters to No and the BES will interogate the socket	#
   # for the buffer sizes.							#
   #									#
   # The TCP window size should be equal to the Bandwidth*Delay Product	#
   # (BDP). This is the number of bytes in flight to fill the entire path,	#
   # and is equal to the connection speed times the RTT( Round-Trip Time) 	#
   # divided by 2. For example, if you have a 100 Mbps path and the RTT is	#
   # 75 ms, the BDP = 100 * 0.075 / 2 = 3.75 Mbits (470 KB).		#
   #									#
   # If you are not sure what to do here, we recommend that you leave	#
   # these values set as is.						#
   #									#
   # BES.SetSockRecvSize=No|Yes - if set to no, then do not set the TCP	#
   #                              TCP receive buffer size. If set to yes	#
   #                              then set the TCP receive buffer size to	#
   #                              the value specified by BES.SockRecvSize	#
   #                              Default is No, use the system TCP window	#
   #                              size.					#
   # BES.SockRecvSize=<number> - This value should be set to the size, in	#
   #                              bytes, of the TCP receive buffer size.	#
   # BES.SetSockSendSize=No|Yes - if set to no, then do not set the TCP	#
   #                              TCP send buffer size. If set to yes	#
   #                              then set the TCP send buffer size to	#
   #                              the value specified by BES.SockSendSize.	#
   #                              Default is No, use the system TCP window	#
   #                              size.					#
   # BES.SockSendSize=<number> - This value should be set to the size, in	#
   #                              bytes, of the TCP send buffer size.	#
   #-----------------------------------------------------------------------#
   BES.SetSockRecvSize=No
   BES.SockRecvSize=65535
   BES.SetSockSendSize=No
   BES.SockSendSize=65535
   
   #-----------------------------------------------------------------------#
   # Defines size of system global memory pool                             #
   #-----------------------------------------------------------------------#
   BES.Memory.GlobalArea.EmergencyPoolSize=1
   BES.Memory.GlobalArea.MaximumHeapSize=20
   BES.Memory.GlobalArea.Verbose=no
   BES.Memory.GlobalArea.ControlHeap=no
   
   #-----------------------------------------------------------------------#
   # This key is set to either single or multiple mode.            	#
   #                                                                       #
   # In single mode the listener handles the client request itself, and    #
   # only one client can connect at a time                                 #
   #                                                                       #
   # In multiple mode the listener listens for client connections. When a  #
   # connection is made it forks another bes process to handle that client #
   # connection and goes back to listening for more connections. More than #
   # one client can connect at a time                                      #
   #-----------------------------------------------------------------------#
   BES.ProcessManagerMethod=multiple
   
   #-----------------------------------------------------------------------#
   # Is the client using the GET or POST method of making requests to a    #
   # back-end server that is a built-in web server module. If the back-end #
   # server is not a web server module, this key/value pair is not used    #
   #-----------------------------------------------------------------------#
   BES.DefaultResponseMethod=POST
   
   #-----------------------------------------------------------------------#
   # Include all module configuration files in the <prefix>/etc/bes/modules#
   # directory								#
   #-----------------------------------------------------------------------#
   BES.Include=modules/.*\.conf$
    
</hai:BesConfig>

Request Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:GetConfig module="ncml_module" />
 </hai:BesAdminCmd>

Response Example

<hai:BesConfig module="ncml_module">
   #-----------------------------------------------------------------------#
   # OPeNDAP NCML Data Handler BES Module Configuration file               #
   #-----------------------------------------------------------------------#
   
   #-----------------------------------------------------------------------#
   # Require dap configuration to be loaded first                          #
   #-----------------------------------------------------------------------#
   BES.Include=dap.conf
   
   #-----------------------------------------------------------------------#
   # modules to load, includes data modules and command modules            #
   #-----------------------------------------------------------------------#
   
   BES.modules+=ncml
   BES.module.ncml=/usr/local/opendap/servers/hyrax-1.8.0/lib/bes/libncml_module.so
   
   #-----------------------------------------------------------------------#
   # Setting the data information
   #-----------------------------------------------------------------------#
   
   # The TypeMatch parameter is a list of handler/module names and a regular
   # expression separated by a colon. If the regular expression matches an item,
   # then the BES uses the associated handler/module. Each <handler>:<regular
   # expression> pair is followed by a semicolon. This is used when creating
   # containers in the BES (the 'set container' command). The example regular
   # expression says to use the 'h4' handler for any file with an extension of
   # 'hdf', 'HDF' or 'eos' which may also end in '.gz' or '.bz2'. In the latter
   # case the file will be treated as a compressed file.
   
   # BES.Catalog.catalog.TypeMatch=nc:.*\.(nc|NC)(\.gz|\.bz2|\.Z)?$;h4.*\.(hdf|HDF|eos)(\.gz|\.bz2|\.Z)?$;
   
   # To test your TypeMatch regular expression you can use besregtest as
   # follows:
   
   # % besregtest type # "nc:.*\.nc$;nc:.*\.nc\.gz$;" fnoc1.nc
   # expression ".*\.(nc|NC)(\.gz|\.bz2|\.Z)?$" matches exactly, type = nc
   
   BES.Catalog.catalog.TypeMatch+=ncml:.*\.ncml(\.bz2|\.gz|\.Z)?$;
   
   #-----------------------------------------------------------------------#
   # NCML module specific parameters
   #-----------------------------------------------------------------------#
   # NCML.RootDirectory - location from BES Root Directory to store the new
   #                      ncml documents.
   NCML.TempDirectory=/tmp
</hai:BesConfig>

.

SetConfig

Element form:

<hai:SetConfig>
     ...BES Configuration Content...
</hai:SetConfig>

Retrieves the BES configuration file.

Request Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:SetConfig>
         BES.ServerAdministrator=admin.email.address@your.domain.name
         BES.User=user_name
         BES.Group=group_name
         BES.LogName=/usr/local/opendap/servers/hyrax-1.8.0/var/bes.log
         BES.LogVerbose=no
         BES.Catalog.catalog.RootDirectory=/Users/ndp/OPeNDAP/Projects/Hyrax/SVNDataProject
     </hai:SetConfig>
 </hai:BesAdminCmd>

Response Example

Submits a new bes.conf file to the BES.

Request Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:SetConfig module="ncml_module">
         BES.Include=dap.conf
         BES.modules+=ncml
         BES.module.ncml=/usr/local/opendap/servers/hyrax-1.8.0/lib/bes/libncml_module.so
         BES.Catalog.catalog.TypeMatch+=ncml:.*\.ncml(\.bz2|\.gz|\.Z)?$;
         NCML.TempDirectory=/tmp
     </hai:SetConfig>
 </hai:BesAdminCmd>

Response Example

Returns a status indicating what happened (Was the configuration accepted, was it valid, did the bes restart, etc)

.

---

Start

Example:

<hai:Start />

Starts the master beslistener process. If a beslistner is already running nothing will be done.

Request Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:Start />
 </hai:BesAdminCmd>

Response Example

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BesAdminCmd xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     <hai:OK/>
 </hai:BesAdminCmd>

<?xml version="1.0" encoding="UTF-8"?>
 <hai:ParseError xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     message text
 </hai:ParseError>

<?xml version="1.0" encoding="UTF-8"?>
 <hai:BESError xmlns:hai="http://xml.opendap.org/ns/bes/admin/1.0#">
     message text
 </hai:BESError>

---