Using Caché on UNIX®, Linux, and macOS

Database and Database Directory Permissions

All databases and database directories must have the group ownership set to the Effective group for Caché processes group and grant full permissions to that group (rw for databases, rwx for database directories). The user who owns the databases and database directories may vary depending on how they were created.

Databases and database directories created within Caché are created with the appropriate permissions. However, if you move, copy or create database directories or databases externally (via scripts or administrator action), you must ensure that the proper permissions are maintained. Failure to set the permissions properly may lead to unexpected and serious errors.

The following example assumes the Effective group for Caché processes is cacheusr and the Owner of instance is cacheowner, although the files may have different user ownership depending on the context in which they were created:

dataset directory    cacheowner    cacheusr    drwxrwxr-x 
CACHE.DAT            cacheowner    cacheusr    -rw-rw----

Daemon Resource Locks

Caché uses advisory file locking to prevent multiple startups of the same instance on different machines. With advisory file locking, a single lock file (in this case, the file clock in the install-dir/bin directory) may be used to exclusively lock multiple resources. The Control Process, Write daemon, and Journal daemon each lock a separate section of the lock file. If this section of the clock file is already locked, startup terminates. The locks held by the different daemons are called Daemon Resource Locks.

A file lock is held by a process until the process terminates. Thus if any lock is held, it indicates that some daemon process on some node is running. It does not indicate, however, whether or not the instance is healthy and running normally.

Cache.ids File

The cache.ids file contains the name of the node where Caché was started. The existence of the cache.ids file acts as a flag to Caché utilities and customer-written scripts indicating whether or not the instance is up and running – this file is often ignored during startup. However, if an error occurs when cache.ids is being read, it will prevent Caché from starting up. In previous versions of Caché, the shared memory identifiers were also stored in the cache.ids file, but this is no longer the case.

Startup Sequence

To best understand the startup sequence, imagine that the instance can be run from two (2) different nodes (machines), node A and node B. The cache.ids file is visible to both nodes, as are the Daemon Resource Locks (for shared files). The shared memory itself, however, is visible only on the node on which it was created (that is, the node where you started Caché).

Starting Caché

To start Caché, run the startup procedure at the system level. This procedure activates either a default configuration file or a configuration file you specify.

If you are not on the console machine, run Telnet and connect to the target machine where Caché is installed. Before you can start Caché on UNIX®, one of the following must be true:

• You are the superuser.

• You have signed on as the root user. (It is acceptable to su (superuser) to root while logged in from another account.)

• Your UNIX® group ID matches the group named during the Caché installation as having privileges to stop and start the system.

  See the “Installing Caché on UNIX® and Linux” chapter of the Caché Installation Guide for information on specifying such privileges during installation.

Start Caché using the ccontrol command:

ccontrol start <instname>

where instname is the name of the Caché instance you want to start. See Controlling Caché Instances in the “Using Multiple Instances of Caché” chapter of this guide for more options and information.

From the shell, a user with any user ID in the sysmgr group can run ccontrol start. This command verifies that the instance is not currently running on the current or another node, creates shared memory and basic Caché daemons, including multiple slave write daemons (SWDs), runs the startup (^STU) routine, which creates additional daemons (for example, ECP daemon), and then allows user logins.

Running Caché

From the shell, a user with any user ID and any group ID (anyuser:anygroup in this example), can run csession (see Connecting to a Caché Instance in the chapter “Using Multiple Instances of Caché”) which executes cuxsession in the install-dir/bin directory.

Running as anyuser:cacheusr, Caché runs its standard startup logic, including Kerberos negotiation, to identify a $USERNAME and a set of login roles. In many cases, this $USERNAME value is associated with the actual user who invoked csession. Thus, while any user may run Caché, the activities of that user once in Caché are defined and limited by the security roles assigned to that user.

The Caché executable is not itself a setgid-executable. It is the responsibility of the csession wrapper to set the group properly on behalf of the user entering Caché.

In addition to csession, you may run Caché using the cache executable in the /usr/bin directory. This command calls csession <default-instance>, setting permissions and opening the Terminal for the default Caché instance. To create the cache executable, designate a default instance by running the ccontrol default <instname> function.

Stopping Caché

Normally you leave your Caché system running. However, if your operating system requires a restart, you should stop Caché before you shut down your system. The Caché maintenance tasks, such as backups and database repair utilities, do not require you to stop Caché.

To stop Caché on UNIX®, the same requirements exist as for starting Caché. One of the following must be true:

• You are the superuser.

• You have signed on as the root user. (It is acceptable to su (superuser) to root while logged in from another account.)

• Your UNIX® group ID matches the group named during the Caché installation as having privileges to stop and start the system.

To stop Caché, from the command line:

1. Use the ccontrol stop command:

   ccontrol stop <instname>
   
   

   

   where instname is the name of the Caché instance you want to stop. (See Controlling Caché Instances in the “Using Multiple Instances of Caché” chapter of this guide for more ccontrol options and information.)

   Caution:

   You can stop Caché with the ccontrol force command, but you should do so with caution because it may result in a loss of data.

2. This procedure invokes the Caché SHUTDOWN utility, which displays a status report. Check for active processes in the report to determine if the next step is necessary.

3. Should it be necessary, broadcast a message to any users on the system:

   Do you want to broadcast a message to anyone? No=> Yes
   Send a message to other terminals. Message => Please sign off
   Terminal => /dev/tty/06
   Terminal =>
   Message =>
   
   

   

4. After sending one message you can send others, until you respond to the Message prompt by pressing Enter.

5. When the system asks if you would like to see another system status, enter Yes to see one, or press Enter if you do not want another report.

6. If you answer Yes, when the system status displays again, identify any active terminals.

7. Confirm that you want to halt by answering Yes. If you answer No, the shutdown procedure quits and Caché continues running.