How to Start / Stop an Instance
In this section, our main purpose will be to explain the necessary steps in order to start and stop instances of VDS using the configurations that you have created within DSGUI. In particular we will explain how DSGUI can be used to start a configuration either locally, or remotely using the Remote Administration Server.
How configurations are started
DSGUI provides two alternative methods of starting a configuration. The process is the same, regardless of whether you wish to start a configuration locally or remotely. The first method simply requires that you click on the "Run" button situated on the toolbar. Alternately, you can start a configuration by selecting the "Run" option from the "Process" menu at the top of the DSGUI main window.
As soon as a configuration has been started, the dsproxy core process will start reading the configuration file that you are working with. Instantly, the "Message Output Area" will become available and will start to display output generated by the running process. This output section is explained in the section ( Logging ).
It is important to note that while multiple configurations can be managed by DSGUI, if you are working on two separate configurations running on the same physical system, it is possible that the two configurations may have port conflicts that you are unaware of. If you try to start two configurations on the same system, you may find that one configuration does not run as expected as it may be unable to bind to some of the ports that it has been configured to use. When running a configuration, it is essential that you ensure that all configured ports for that configuration are available for the system that you intend to run the configuration on.
How configurations are stopped
In order to stop a configuration that has been started by DSGUI, you have two different options, you can either use the "Stop" button on the toolbar or you can select one of the two different methods ("Forceful Stop" or "Graceful Shutdown") under the "Process" menu at the top of DSGUI window or under the drop down menu on the toolbar.
A "Forceful Stop" will be triggered when the "Stop" button on the toolbar is selected. The "Graceful Shutdown" action will be enabled depending on the the availability of the Administration port and its "Graceful Shutdown" functionality Administration Port Configuration .
Forceful Stop
Forceful Stop simply kills the running dsproxy process. This will, of course, stop all processing instantly. This means that all requests that are still being processed within the running instance will be killed along with VDS. As a result, we recommend that where possible, you make use of the Graceful Shutdown option.
Graceful shutdown
Graceful Shutdown provides an alternative method to stop a running instance of dsproxy. When the Graceful Shutdown feature is used, a special signal is sent to the dsproxy process, notifying it of the shutdown request. VDS will then cease to accept any new requests on all of its listeners. It will then attempt to complete all of the processing for existing requests within the system. Once VDS has finished processing all requests, or after the configured timeout period has been exceeded, the running process will terminate. You can find more detailed information on how the "Graceful Shutdown" process works in Graceful Shutdown
This method is of course safer than Forceful Stop, as it allows for "hot" instances (instances that are still processing requests) to finish processing before they terminate. Moreover, no additional steps are required (like stopping all client applications), to ensure that no data is lost.
On Unix systems, it is possible to configure a Watchdog service 
, which is a process that will ensure that any dsproxy process that stops is automatically restarted. Therefore, if the Watchdog is enabled and you perform a Graceful Shutdown the instance you are trying to stop will be restarted. You will recieve a Warning dialog, notifying you that you should perform a Forceful Stop to actually terminate the instance.
Running a VDS Instance as a Windows Service
For Windows Operating Systems, it is possible to run individual instances either manually from the shell, or to have them registered as Windows Services that can be invoked at system startup.
An instance created with DSGUI can be started manually using the "init-dsproxy.bat" batch script that you can find in the VDS installation directory. This script is used by the Remote Administration Server to start and stop instances, and it works by registering the configuration as a service and then using the OS facilities to manage (start / stop / restart) it.
Before running the batch script, it is important to check that the script is searching the right location for your configuration. In the file located at:
C:\Program Files\Dell\VDS\RX.X.X\admrem\admconf
check that the line containing the "configdir" directive contains the correct path containing your configuration.
So, to register your configuration as a service simply run the bat file. The syntax for this command is:
init-dsproxy.bat
In the above example,
- check
-
It will register the service (if it is not already registered) and check if it is running
- start
-
It will register the service (if it is not already registered) and start it
- stop
-
It will register the service (if it is not already registered) and stop it
- restart
-
It will invoke the stop and start functionalities
- gdump
-
It will generate a core dump and restart the instance (for debugging purposes)
- condrestart
-
It will invoke stop and start functionalities (if the instance is already running).
- remove
-
It will remove the service if already registered
Once a configuration has been installed as a service, you can use your Windows Service interface to manage it, configuring it to start automatically if you want. The configuration will be listed in Services as "VDS R6.1.0 [ confs - configuration_name ]".
Logging
In the following sections we will try to explain how DSGUI interacts with the logging generated by a running VDS instance. We will explore how the logging information is generated and the different options that a DSGUI user has to view and explore its content.
How logging works
A running VDS instance generates several different kinds of logging information that can be viewed in the DSGUI that is managing it. The log data is generally stored within the 'logs' directory inside the directory for the instance configuration. Log data may be stored for these 3 different destinations:
- STDOUT
-
This destination will receive the information that the VDS instance "prints" while it is running. Most information generated by the scripts and plugins ( Plugin configuration ) is sent to this destination and should be checked here. Changing the debug level (verbosity) of a plugin or calling "print" functions inside your scripts, will affect the output written to this destination.
- STDERR
-
This destination is mainly used by the "core" of the VDS engine. All internal engine processing information (opening of ports, decodification errors, script compilation problems, etc.) is written here. Plugins do not use this destination at all, but if you want, a custom script can write to this output using the "perr" function.
- File
-
Any custom script can use API functions to write information to any file within the filesystem where the VDS engine that is processing the script can write. Also, all the logging plugins can optionally write their output to files instead of using STDOUT or STDERR. It is a good idea to always place files where logging information will be written inside the "logs" directory of your instance, as they will be easier to access.
The STDOUT and STDERR logs are automatically presented as separate tabs within the Message Output area in DSGUI when an instance is started. A folder icon toward the top of the Message Output are can be used to open any other external log file that you wish to watch. By default, the file explorer will open within the logs directory for the configuration that you are working with.
Log files are also accessible via the Web-based Remote Access Server (WRAS) if this service has been configured correctly and is running.
Controlling log levels on-the fly
Log levels can be changed on-the-fly by sending a modification request through the Administration port. As a result, any of the log levels specified within the DSGUI application are capable of being changed while the instance is running without requiring a restart.
To change the log-level on the fly, using the DSGUI application, the appropriate log item should be navigated to within the configuration tree. A button titled "Apply Now" will be visible next to the logging options. This button will only be available if the instance is actually running. If you change the log level while the instance is running, you will be able to click on the "Apply Now" button to change the log level for the live instance.
Managing logging
As already discussed, the logging facility will capture data destined for STDERR and STDOUT and will output this data to log files stored within the 'logs' directory for a configuration. These files are displayed inside the Message Output Area when an instance is started within DSGUI. The Message Output Area allows you to open other custom log files, and to control how you view logging output.
Fig-64: Managing logging in the Message Output Area
The lower section if the Message Output Area is a tabbed panel with each of the different logging destinations configured for the different plugins, including the STDOUT and STDERR outputs. This panel allows you to select the destination logging that you want to see, and you can change the output that you are viewing just by clicking on a different tab.
The upper section is used to send commands to the currently selected output destination using the different buttons. The commands that you can send are:
- Show a new log file
-
Opens a file selector that allows you to add a new file to the tabbed panel.
- Close this log file
-
Removes the currently selected destination from the tabbed panel.
- Fetch this log from the start
-
Restart reading the selected destination logging file form its beginning.
- Fetch this log from now on
-
Start reading the file from now and stop sending past information.
- Text field + RegEx + Highlight
-
Tells DSGUI to highlight (in red) each instance of the text selected in the text field as it appears in the log. If the RegEx option is selected, the contents of the text field will be interpreted as a regular expression and matches will be highlighted within the log.
Regular Expression Basics
The syntax used for regular expressions within DSGUI is the same as that supported by Java (which is quite similar to that used in Perl). Some basic examples follow, but you should check the documentation of class java.util.regex.Pattern.
. Matches any char
\d Matches any digit
\w Matches an alphanumeric char
\s Matches any space
[ab] Matches 'a' or 'b' characters
^a Matches lines that start with an 'a' char
a$ Matches lines that end with an 'a' char
a+ Matches 1 or more 'a' chars
a* Matches 0 or more 'a' chars
a? Matches 0 or 1 'a' chars
a{2,4} Matches 2, 3 or 4 'a' chars
(\w*=\w*,)+dc=org[^\w,] Matches canonical dns hanging from dc=org (approx.) REMOTE ADMINISTRATION SERVER (RAS)
Overview
The Remote Administration Server (also known as RAS) is an agent process that runs, along with VDS, on a server with the purpose of allowing the instances to be operated and managed remotely.
The RAS is basically composed of two tools or functionality sets:
- DSGUI Interface
-
Receives and executes commands sent from a DSGUI instance running on another computer. This process effectively makes an instance of VDS manageable by remote DSGUI instances.
- Web Remote Administration Server (WRAS)
-
Offers a web interface to users accessing the RAS using a web browser. While it offers a more basic set of operations, it has the advantage that nothing other than a web browser is needed as a user agent.
Both the DSGUI Interface and the WRAS are handled by the same VDS process and are configured in the same file, but each can be partially or completely deactivated by configuring the Role Settings.
Purpose Of RAS
The Remote Administration Server is a feature that was included within version 4 of VDS. Prior to the implementation of this feature, a remote instance could only be managed by manually connecting to the instance to copy configurations, edit files or run programs, or by running DSGUI in each of these instances (which is not allowed in many production environments).
In order to overcome these difficulties RAS was developed to facilitate the administration of configurations across a range of environments and servers:
-
With the DSGUI Interface functionality of RAS, a single DSGUI instance, installed on a local computer, can be used to manage instances of VDS across completely separated development, testing, and production platforms within your organization. DSGUI and RAS will collaborate to make development, testing and monitoring seamless across various environments and servers. An introduction to the different options to support multiple environments can be found in the section titled How DSGUI works .
-
The Web Remote Administration Server (WRAS) functionality offers a simpler alternative to remote administration: The user can access the remote instance and perform a basic set of operations directly using a web browser. This removes any requirement to install or run DSGUI or any kind of software (besides the web browser itself).
The usual approach is that in the development and testing phase of a project the instances are created, debugged and put to work using DSGUI with the RAS interface. Once the functionality is stable and during the production phase, the instances can be remotely accessed with WRAS for monitoring and to perform occasional basic operations as well as the debugging of minor problems.
What You Can Do With RAS
A RAS instance is primarily responsible for taking care of the management and operation of a VDS instance. These tasks represent the following actions:
- Management
-
Create / Load / Save / Remove Configurations
- Operation
-
Start / Stop / Check Status / Show logs
When working with RAS via the DSGUI interface, DSGUI will create a virtual filesystem space that allows you to treat remote and local configurations in a unified way, so that you can manage all of your configurations from a single instance of DSGUI regardless of where they are located.
Although the WRAS interface makes it possible to edit existing configurations and functionality scripts, it currently does not support the option to create new configurations or scripts.
RAS, either through DSGUI or WRAS, also facilitates the option to execute specialized commands related to the management and monitoring of VDS instances.
How RAS Works
RAS is built as a specialized local configuration that is included in the VDS package and that can be run by the VDS core process. As a result, any server on which VDS has been installed can run the RAS service. The RAS configuration is used to facilitate communications with a user that is accessing the server remotely. In this way, the monitoring and management of configurations will take place locally on the RAS server, but can be managed remotely by an instance of DSGUI or through a web browser.
The RAS instance listens for HTTP requests on a specified port, targeted for a given set of URLs.
For interactions with DSGUI, the RAS instance receives POST requests sent by DSGUI at the "/main" URL. The content of these requests is an XML message that corresponds to any of the different operations that composes this interface.
The WRAS functions by receiving GET or POST requests sent by the web browser of the user at "/wras.htm", "/wins.htm" or "/wlog.htm". These request have information encoded about the operation to be performed.
Both tools make use of a session-based authentication layer that presents a login screen to an unauthenticated connection, and issues a session identifier in the form of a cookie when the user logs in. The session identifier is used to track the session and to handle an automatic timeout facility. Once a user has been authenticated, the authentication layer ensures that the user has the appropriate permissions to perform the operations that the user attempts via either DSGUI or via the WRAS. If no action has been performed by the user for a configured period, the session on the WRAS will expire and the user will be required to login again in order to perform any further actions.