Troubleshooting Sigma Web Framework issues

If you have access to the computer that is running the Sigma Framework, you can easily reset the default username and password back to username admin password admin. The default login database is installed in the installationDirectory/apache/install directory, and these files can be manually restored using the following procedure:

1. Login to the platform running Sigma.
2. Copy the installationDirectory/apache/install/passwords.dat file to the installationDirectory/apache/passwords.dat file. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender. (This is the default password file for the Apache HTTP server.)
3. Copy the installationDirectory/apache/install/pass.cnf file to the installationDirectory/config/pass.cnf file. (This is the default password file for the Sigma Framework.)

This will permit you to login to the system using the default username of admin, password admin. Note that this clears the password database back to its default value. All login information is lost and will not be recoverable.

If you have access to the computer that is running the Sigma Framework, you can manually add logins. This is a bit more difficult than resetting the login database, but preserves the logins to the system. The procedure for manually adding a password is as follows:

1. Login to the platform running Sigma.
2. Change working directories to the installationDirectory/apache directory. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender.
3. Issue the following command at a command prompt, needed to add a new password to the passwords.dat file: htpasswd.exe -b passwords.dat temp temp. (This adds a username temp, password temp to the Apache passwords.dat file.)
4. Manually edit the installationDirectory/config/pass.cnf file, such as with notepad.exe. The file contains encrypted login records, but you can add a record in clear text. Append to the file a record temp temp admin none (five words, space delimited). Make sure you add a terminal new line to the new record. Save the file.
5. Login to the Sigma web interface with username temp password temp.
6. Go to the System > Logins screen and reset your original password, and optionally delete the temp username created above.

The htpasswd.exe program is the standard Apache utility for managing passwords on the system. Command line options for this utility are available by executing the program with no arguments. More information on this utility is available from the Apache Group. (Consult the web or a variety of other sources.)

The pass.cnf file contains a list of encrypted passwords. Each record contains the username, password, access, and e-mail address of a user. Each encrypted record begins with a // character. When reading the pass.cnf file, if the record is not encrypted, the record is assumed to be a clear text representation, and the program continues. Next time that the pass.cnf file is modified via the Sigma System > Logins screen all the passwords are re-encrypted.

The htaccess.txt file contains a pointer to the password file. Users can copy this file to different directories to enforce a login prompt when that directory is first accessed. This file is first configured when Sigma is installed, and contains the full pathname to the passwords.dat file. If this file is tampered with, or corrupt, users will not be able to login to the Sigma system. In this case, the administrator must reconfigure the system. An experienced administrator can simply edit the htaccess.txt file. You can also just execute the installation procedure system/CO-install.exe, which will reset all the passwords back to the default username admin, password admin.

If you copy files into the sigma-web directory, and they do not appear as navigation tabs, the most likely reason is that you have failed to follow the strict naming conventions required by Sigma Framework for naming files in this directory. Sigma silently skips over any file in the sigma-web directory that does not following the precise naming conventions.

Each object in the sigma-web directory needs to have a three digit number (with possible leading zeros) followed by an underscore character, followed by the tab name, followed by a suffix of either dir, txt, htm, html, cmd, bat, or exe, as documented in Creating-Sigma-Web-Framework-advanced-applications. Any file that does not follow this precise naming convention is ignored by the web.exe program.

Verify that you have precisely followed these naming conventions. Further verify that the file suffix values actually represent the nature of the file (for example, verify that any object with a dir suffix is actually a directory.) This is an easy mistake to make. Because the Sigma names are slightly complex, you can very easily forget to prefix an object with exactly three characters, or leave off a dir suffix from a directory.

Note that file and folder permission issues, while often suspected as the cause for this problem, are rarely the actual problem. The HTTP server runs as the Local System user, which generally has access to all files and folders on the system.

The most likely reasons for this occurring are that the CO-Apache.exe program is not running, or running at a port number different from that which is expected, or that the machine running Sigma is not accessible to the network, or a problem with an Apache configuration file exists. There is a methodical way to troubleshoot this problem as follows:

1. Login to the platform that is running the Sigma Framework.
2. Using the Windows Task Manager, confirm that the CO-Svc.exe program is running. If this program is not running, it should be started using the Windows Service Manager, or via the net start sigma command at a command prompt.
3. Using the Windows Task Manager, confirm that the CO-Apache.exe program is running. (There should be precisely two instances of this program running on the platform)
4. If the CO-Apache.exe program is not running, but the CO-svc.exe program is running, then the CO-Apache.exe program may have stopped due to an internal Apache error. Try starting Apache manually. At a command prompt, changing working directories to the installationDirectory/apache directory and execute the command: CO-Apache.exe. Observe any error messages, and take corrective action. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender.
5. If the CO-Apache.exe program is running, but is still not accessible, then the Apache server it may be listening at a port number that is unexpected. Check the conf/apache/httpd.conf file to see what port number Apache is listening to (i.e. check the value of the Port entry in the file.) Then try accessing the Apache server by incorporating that port number into the URL, such as "http://localhost:88".
6. If you are able to access the Apache server from the localhost platform, but not from some other program, check to make sure that the Proxy settings of your browser permit access to the local area network. On Internet Explorer, you can access Tools > Internet Options > Connections > Lan Settings to view or modify your Proxy settings.

Note that Virus Protection programs and port blocking security software can interfere with the startup of the Apache server, and interfere with the installation procedure of the Sigma Framework. If you are running the McAfee virus protection program (or some other port blocking software), temporarily disable that program to see if it corrects the problem.

Finally, note that the netstat –a –p tcp command, issued at a command prompt, will list the current TCP service ports that are open on your platform. You should verify that the service port used by Apache (that is configured in the apache/conf/httpd.conf file) is busy ONLY when the CO-Apache.exe program is running.

The most likely reason that your program works outside of Sigma (such as at a command prompt) but fails to work correctly within Sigma is that you have programmed some dependency that exists only in your programming environment.

Note that the working directory for all programs executed by Sigma is the installationDirectory/s-cgi directory. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender. All pathnames used by a program should be relative to that directory. Further note that Sigma executes programs as the "Local System" user, and inherits that environment.

A simple way of getting the environment used by Sigma programs is to create a simple test batch file, called 999_Environment.bat, and copy that program into the sigma-web directory. In that batch file, issue the single SET command, which will list all the environmental variables of the program. (Also, you can configure other environmental tests.) When you access the Environment tab, you will see all the environmental variables that are present.

Finally, you can always include debug statements in a program, and write debug data to a log file as a CGI program executes. This provides a simple way to trace execution of a program.

Sigma does not provide access to any decryption function. The Sigma encryption service is one way. The actual encryption algorithm uses a block, rotating, time sensitive cipher algorithm, which is highly secure. Once the data is encrypted, there is no obvious way to decrypt the data outside of Sigma.

Note that Sigma is designed so that it is never necessary to actually decrypt the data components. The user encrypts URL arguments. The web.exe program, prior to executing any user programs, decrypts these arguments. The user receives the unencrypted data as command arguments.

Finally note that the password file is double encrypted by different methods, so it is even more secure that the URL encryption, and cannot be subverted (such as by attempting to pass the login records as arguments to user defined scripts.)

As with any security system, it may be possible for an expert programmer to decode or decrypt the encrypted data (such as by editing the Web.exe program with a binary editor, to extract the decryption method employed.) Any Attempts to do this is, or to subvert the encryption process, is a DIRECT VIOLATION of the Sigma license, agreed to by your organization. Consult the LICENSE.txt file for more information.

The answer to this question depends upon whether you are encrypting the URL or not, because the two mechanisms for passing arguments via a URL depend upon this.

1. If you are not encrypting the URL, then command arguments are passed using the standard & character to separate the arguments. Also, you must be very careful not to introduce special characters into the arguments, such as unquoted spaces, or an equal sign. (This may entail a good deal of lookup of HTML character codes!)
2. If you are encrypting the URL, command arguments must be appended to the pathname of the executed program, separated by semicolon : characters. The user must quote any semicolon in a passed argument with a backslash. The data does not have to otherwise be formatted.

The 010_DisplayArgs.bat file might be useful in debugging this problem. For more information, see Encoding-arbitrary-URLs-and-arguments.

Additionally, you can view the source HTML document (via the normal browser View Source option) to see the command arguments that are launched with any subprogram. (This is an implicit function of the SG_run_command() function, discussed in Miscellaneous-utility-functions.) Whenever the "web.exe" program or any subprogram executes another program using this function, the decoded command and arguments are incorporated into the source HTML as commentary.

Sigma supports any programming language, including all of the above, plus others, such as Java. The user must create a wrapper .cmd file, which launches the interpreter for the language and references the script. This allows a user, in addition to launching an interpreter, to also have full control of the environment in which the interpreter is launched, including the setup of any environmental variables, working directories, permissions, etc.

This technique is extremely straightforward. Some users might object to the fact that their scripting language needs to have a batch file wrapper, but it actually provides a vast amount of flexibility that often doesn't exist in other frameworks. Through the enforcement of this simple rule, a vast amount of extensibility is made available that is otherwise extremely problematic to programmers.

Note that the batch file can consist of a single line. (Also recall that, in a batch file, you can turn off echoing of command output by starting the program with the command @echo off, which inhibits command line echoing.) Also note that arguments from the batch file can be passed to the third party programming language using the %1%, %2% variables.

A discussion of batch file programming is beyond the scope of the question, but it should be stated that most programmers are unaware of how powerful batch files may be, especially in later versions of the Windows operating system. Consult the web for information on batch file programming, or seek information from a multitude of other sources.

If you are launching Perl, Ruby, Java, or any other programming language within Sigma, you must use a batch file that begins with a cmd extension AND NOT a bat extension. Sigma Framework automatically displays output of a .bat file as preformatted text (without HTML). The cmd extension is used to display raw HTML output. This is the only difference within Sigma between these two file extensions.

Generally a .bat file is mainly useful (over a .cmd file) in order to display raw text files, or execute system programs such as netstat, which deliver preformatted text as a standard part of their operation. For example, the user can create an 800_SysTools.dir/100_Netstat.bat file wrapper, and an 800_SysTools.dir/200_IpConfig.bat file wrapper, and other screens which run system commands. This technique can be used to generate a variety of simple to program screens that are useful for system management.

The Navigation Tab Colors are set by the System > Parms screen, and the data resides in the ./config/sparms.cnf file of the Sigma Framework. The colors must either be in RRGGBB hexadecimal notation (which is the standard HTML format) or must be one of the HTML predefined color names such as Red, Blue, Azure, Burlywood, Navy, etc. (A vast variety of predefined color names are supported by all browsers.)

The most likely reason your colors are unexpected is that you accidentally introduced an errant character in the tab color while editing the Parms screen. You can set the colors back to default (along with all other parameters) by accessing the System > Parms screen, and then clicking the Default button on the Edit screen. Or, you can simply edit the ./config/sparms.cnf file with a text editor and carefully make color changes.

Note that the text color and the field color should be selected for a good contrast. Generally, users may want to confine the text colors to be either WHITE or BLACK for the best contrast with any Tab color field.

A developer can remove or rename the Parms screen by accessing the sigma-web directory. The screen is not required for normal operation of the Sigma Framework, and is provided as a core application only for user convenience. Rather than using this screen, the administrator can simply edit the config/sparms.cnf file with a standard text editor, such as Notepad.

A typical system might have hundreds, or even thousands of nested tabs. Consider that a system with five tabs at each of three levels will have 125 screens. A system with eight tabs at four levels will have 4096 different screens.

At any given level, the maximum number of tabs is actually limited to five hundred per level. However, this will cause a horizontal scroll bar to be opened, and make navigation of the system very difficult. In practice, depending upon the size of each tab name, a typical level of navigation might have between one and ten different tabs.

As with any system, the organization of the data (in terms of directories and subdirectories) is critical to the simplicity of the system. It is fairly easy to re-arrange the programs and navigation tabs within Sigma using the Windows File System Explorer or other technique. Developers should exercise moderate design deliberation needed to create an ergonomic and logical arrangement of tabs.

The disabled user message is displayed under two different circumstances, as follows:

1. The user is actually disabled in the System > Logins screen. This is a specific setting that Administrators can use in order to prevent a particular user from accessing the system.
2. The user is defined in the HTTP server, but not in Sigma, and the default user setting is set to disabled. This is a way of enabling Windows Directory Services as the means of authentication, but disabling any user that is not specifically registered with Sigma.

If you are using Windows Directory Services, and you wish all users to be able to access Sigma Framework programs as Guests, you can set the default user, in the System > Parms screen to be guest. Then, if the user is registered on the network, that user can at least view some of the Sigma screens. In that case, only those users who are registered as disabled will receive disabled user screens.

This method provides a good deal of flexibility in who can access Sigma Framework, especially in the maintenance of passwords. For example, you can use Windows Authentication (with IIS) and limit only those users registered with the program to access screens. When users change their passwords on the network, access to Sigma Framework changes correspondingly without the need for changing passwords within Sigma.

Note that when using IIS, or some other server making use of Windows Directory Services, the passwords configured in Sigma are essentially ignored. The Sigma passwords are pertinent only when using the default configuration of Sigma and the Apache HTTP server.

Normally, Sigma works perfectly with IIS. However, there are a variety of arcane permission problems that can prevent easy integration of Sigma Framework and IIS, depending upon the security policies implemented on the host platform and network. Some of these problems may require intervention by Technical Support in order to fix (such as using Sigma with "hardened" versions of IIS.)

The most obvious and common reason that Sigma is not working with IIS is that the program virtual directories have not been correctly configured. Verify that the installationDirectory/s-cgi directory folder corresponds to the /s-cgi URL, and that this URL provides read and execute permissions. Also verify that the installationDirectory/s-html directory folder corresponds to the /s-html URL, and that this URL provides at least read permissions. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender.

The installationDirectory/sigma-web and other folders within Sigma Framework SHOULD NOT normally correspond to URLs on the system, to prevent unauthorized viewing of files and executables. (In some situations, where security is not an eminent concern, these folders may be made public, depending upon the goals of a developer.) Consult IIS documentation on security policies for more information.

Normally, Sigma authenticates users only by username. However, using the IFMEMBER.exe utility that comes as a standard component of the Windows SDK, it is possible to authenticate users by group rather than by name.

For example, it is possible to grant admin rights to any user in the Admin group, and grant guest rights to any user in the Design group, and deny all other users on the network. This implementation may require the help of Technical Support. Contact us for more information on this particular implementation.

Many Sigma Framework evaluation versions (in particular those versions that have been downloaded from the Web) omit these objects from the distribution. Developers interested in the Sigma Framework Development SDK should contact us.

If you have installed these components, you will find them in the installationDirectory/SDK directory of the site. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender. This directory furnishes link libraries, include files, the Sigma.dll, coding templates, and additional documentation.

If the Sigma SDK does not exist at your site, these items can be installed in the system without affecting other components.

Note that without these components, developers can still create applications using their favorite programming and scripting languages. The sigcmd.exe utility is particularly useful and essential for these programming efforts, and this utility is a standard part of all Sigma Framework distributions, located in the installationDirectory/system directory. For more information and the sigcmd.exe program, see Sigma-Web-Framework-API.

Because Sigma Framework does not scatter DLLs or other system files across the platform, it can be easily relocated. Simply copy the Sigma directory to its new location. (You can also Zip Sigma and Unzip at to its new location.) Once the directory is copied, the administrator can manually execute the system/CO-install.exe program to reconfigure the Apache server to work with the new path.

1. Stop the Sigma Framework Server using the Windows Service Manager, or by executing the net stop sigma command at a command prompt.
2. Save the config/pass.cnf and apache/passwords.dat files. (They will be used in step 5 below.)
3. Copy the Sigma root directory to the new location. This can be a new disk on the system, or a different machine on the network.
4. At the new location, run the installationDirectory/system/CO-install.exe program, and follow the steps needed to finish the install procedure. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender.
5. Copy the config/pass.cnf and apache/passwords.dat files, preserved in step 2 above, into their new locations.

As a final step, you can optionally uninstall the old location using the standard Windows Add / Remove Programs facility.

Note that the above steps are sufficient for re-installing the Sigma Framework core files. Specific applications within the Framework may require special procedures, depending upon their functions and design. Although the above steps may be sufficient for moving these applications, the documentation associated with these applications should be consulted for details.

The final cleanup of Sigma files is left as an obligation to the user. This is made easy by the fact that Sigma does not scatter DLLs or affect system files, hence the uninstaller can simply drag the Sigma root directory to the Windows Recycle Bin in order to dispose of these files.

The system/CO-uninst.exe program (which is normally executed by the Windows Add/Remove Programs facility, but which can also be executed manually) removes the Sigma service and cleans up the registry. It does not remove any files on the disk. Due to the simplicity offered by the total self-containment of Sigma, the final removal of these files is left as a simple manual step. This enhances data security, and provides substantial resistance to accidental deinstallation of important data.

The details associated with safeguarding system data depend upon the particular applications that reside in Sigma. Generally, the only data that is specific to the core Sigma Framework is found in the few files within the ./installationDirectory/config directory. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender. If these files are periodically archived, they can be restored in order to preserve the Sigma usernames, scheduler information, screen colors, and other configuration items.

Applications within the Framework may require special backup procedures, depending upon their functions and design. The documentation associated with these applications should be consulted for details.

The scheduler program permits files to be run hourly, daily, weekly, and monthly, but not each minute. If a dedicated process is required to accomplish this, you can create a script or batch file that loops, executing commands, and sleeping for 60 seconds. This program can then be launched via the Sigma Scheduler start directive, on program startup, where it will run as a persistent program on the system.

The Sigma scheduler function permits any process to be started as a service. The program is terminated automatically when the system stops. This affords a mechanism to run any persistent process in background, including batch files or scripts that perform periodic action such as that described above.

You can run batch files without modification or special regard using the Sigma Scheduler interface, however the name of the batch file will not be visible during execution. This is because the scheduler launches the CMD.EXE program to execute the batch file, and that is the name you will see in the Windows Task Manager. It may therefore be a good idea to provide some error and status logging within the batch file to ensure it is actually running.

The only log file generated by the core Sigma Framework is the Sigma Service program log, which system/CO-svc.log file. This file contains an indication of processes that have been started, processes that have unexpectedly terminated, and any messages due to the log directive of the Sigma Scheduler. The file is automatically deleted and restarted each time the CO-svc.exe program starts.

The Apache server provides an extensive logging facility, detailed by the Apache group. By default, the CO-Apache.exe program creates the apache/logs/error.log file, containing any errors experienced by the Apache server. Users can also log access, and many other indications. Consult the Apache Group website for details.

Applications within the Framework may have special logging capabilities depending upon their functions and design. The documentation associated with these applications should be consulted for details.

Files in the sigma-web directory should contain spaces. (The closest equivalent would be an underscore or perhaps a hyphen.) This constraint enforces uniformity between Sigma applications. For consistency, Sigma developers should select names for their programs (and their corresponding tabs) that do not contain spaces. If a program contains a space as part of its name, the program name will wrap, increasing the height of the tab beyond normal. This may affect other aspects of the display as well.

The most likely reason for this is that the web page uses relative naming in hyperlinks, as opposed to absolute paths. Because the web.exe launches programs, all relative paths are with respect to the /s-cgi/ directory. This may have negative consequences to existing documents that are moved into Sigma. It may entail some modification of these documents.

One way to ensure that URLs work is to make all URL paths absolute. For example, the link "<img source=images/my.gif>" can be converted manually with an editor to be "<img source=/images/my.gif>" to correct this problem. (Note the forward slash, added to the source= attribute.) This decouples the link from the base URL of the document, and insures the proper image is accessed.

Rather than editing many different documents and URLs, developers can employ the HTML <BASE> tag, in the s-html/s-header.html file, to provide a base URL for all other URLs in the system. This is a simple way of correcting this problem, but may have undesirable side effects associated with some user supplied documents, depending upon the particular applications running in the framework. Developers should try this, to see if it is a good solution.

The tab colors are stored in the installationDirectory/config/sparms.cnf file, and can be parsed by application programs and scripts. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender. If a developer is using the Sigma.dll and Sigma SDK, there are various methods (SG_get_tab_on_color(), for example) that can be used to get the configured colors. Otherwise, the application program can parse the colors, or any other value, from the configuration files.

All configuration files within Sigma Framework use the exact same standard way of representing configuration data, which makes this activity somewhat easy. All configuration data consists of a unique keyword identifier, followed by one or more white spaces, followed by a value.

Sigma employs a standard version of Apache, at least with respect to all configuration items and values. The Apache TCP port number is specified in the apache/conf/httpd.conf file, identified by the Port directive. Users can stop the Sigma Framework Service, edit this file to provide a new value, and restart the service. This will change the TCP port number at which Apache listens for service requests.

The configuration data associated with Apache is quite extensive, and is beyond the scope of this question. The configuration files that come with Sigma contain only a very small subset of the total directives available to users. In some ways, this helps simplify the maintenance of the Apache server, and is a reasonable implementation. More advanced directives can be added by experienced users.

The Sigma Framework installer, residing in the system\CO-install.exe file, provides a method for executing extra commands. Developers can create the system\CO-INSTALL.bat file, which is automatically executed by the installer as a last step in the installation program. This provides a method for launching other installers, and performing extra installation work that may be required to support a particular Sigma application.

To launch another program, the developer should make use of the standard start batch command, which allows foreground processes to be opened from background processes. (The CO-INSTALL.bat file normally runs in an invisible console, hence cannot prompt for input.) For assistance, type start /? at a command prompt.

Note that there is also a facility to run special uninstall commands. When executing the system\CO-uninst.exe program, after the user clicks the Finish button, the system\CO-UNINST.bat file will be executed (if it exists). The process will continue after the uninstaller exits, and can be used to perform additional deinstallation work for a developer.

There is only one likely reason for this happening: The disk that is executing the Sigma Framework is out of space. When posting arguments, a short file is created in the installationDirectory/temp directory. Replace installationDirectory with the directory in which you installed the product. The default directory is C:\Program Files\BMC Software\BMC Defender. If the file cannot be created, then form posts will stop working. (Typically, buttons will have no action except to redisplay the screen, although this depends upon the application program.