Configuring Cognos TM1® TurboIntegrator function security in Cognos Insight

When you open an IBM® Cognos® Insight workspace that has been shared through IBM Cognos Connection, you might want to restrict the execution of some TurboIntegrator functions, especially functions that can destroy or modify data files.

Several TurboIntegrator functions exist that can write files, delete files, and execute commands. When you receive a shared Insight workspace, it is possible that TurboIntegrator processes within the workspace might include functions that perform undesirable actions. To prevent processes from performing potentially harmful actions, your Insight installation includes a configuration file that is named TMIFunctions.cfg, which can be used to prevent or restrict the execution of TurboIntegrator functions.

Any TurboIntegrator function can be entirely prevented from executing. The ASCIIOutput, TextOutput, and ASCIIDelete functions can also be configured to run in restricted mode. When a function runs in restricted mode, it is limited to acting upon files within the TM1 server data directory and its subdirectories.

When you install IBM Cognos Insight, a default version of the TM1Functions.cfg file is created in <pa_install_directory>\tm1_64\coginsight\bins\bin_10.3.1.1514\tm1\bin. You can modify this configuration file to further restrict function execution or allow function execution.

The default version of the TM1Functions.cfg file appears as follows:

ExecuteCommand=0
AsciiOutput=1
TextOutput=1
AsciiDelete=1

When a function is set to 0 in TM1Functions.cfg, the function is prevented from executing. Any attempt to execute that function causes TurboIntegrator to throw a security exception.

When a function is set to 1 in TM1Functions.cfg, the function runs in restricted mode. Only the ASCIIOutput, TextOutput, and ASCIIDelete functions can be set to run in restricted mode.

When a function is not present in TM1Functions.cfg, it runs completely unrestricted.

Examples of functions running in restricted mode

When a function is configured to run in restricted mode, any relative path passed as an argument to the function is assumed to be rooted in the TM1 server data directory and is allowed. Any absolute path to a directory above the TM1 server data directory prevents the function from executing and causes a security exception to be thrown at runtime.

Editing the TM1Functions.cfg file

  1. Open the TM1Functions.cfg file in a text editor.
  2. To completely prevent a function from executing, set the function name to 0. For example, ExecuteCommand=0 or ServerShutdown=0.
  3. To allow a function to run in restricted mode, set the function name to 1. For example, AsciiDelete=1.Only the ASCIIOutput, TextOutput, and ASCIIDelete functions can be set to run in restricted mode.
  4. To allow a function to run unimpeded, delete the function name from the TM1Functions.cfg file.
  5. Save and close the TM1Functions.cfg file.

Example 1

Assume AsciiDelete=1 in TM1Functions.cfg. In this case, the function

ASCIIDelete(‘logs\sample.log');

is allowed and deletes the file sample.log from the logs subdirectory of the TM1 server data directory.

However, the function

ASCIIDelete(‘c:\autoexec.bat');

will not execute and will cause a security exception because it specifies a file at the root level of the drive, which is above the TM1 server data directory.

Example 2

Assume TextOutput=1 in TM1Functions.cfg. In this case, the function

TextOutput(‘logs\sample.txt', ‘this is sample text');

is allowed and writes a string to the sample.txt file in the logs subdirectory of the TM1 server data directory.

Conversely, the function

TextOutput(‘c:\autoexec.bat', ‘del *.* -r –f');

is not allowed due to the path being specified at the root level of the drive. This function will cause a security exception to be thrown at runtime.