Hyrax: BES Administrative Commands: Difference between revisions
From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽
Line 44: | Line 44: | ||
=== GetConfig === | === GetConfig === | ||
Element form: | |||
<hai:GetConfig /> | <hai:GetConfig /> | ||
<hai:GetConfig module="module-name" /> | <hai:GetConfig module="module-name" /> | ||
Revision as of 21:54, 26 May 2011
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
Element form:
<hai:GetConfig /> <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>