Hyrax: BES Administrative Commands
From OPeNDAP Documentation
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 />
Element form:
<hai:GetConfig module="module-name" />
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>
