Tag: Cradle database

A Cradle database is a collection of files for each project that store the data written and retrieved  by the Cradle Database Server (CDS)

Posted on

Open Database Connectivity (ODBC)

Open Database Connectivity (ODBC) is an application that allows different types of databases to interface through the use of a library containing data access routines. Cradle now supports connections to DISAM, Oracle and MySQL.

Connection to Different Data Storage Types
This diagram shows the logical representation of the project data storage

Installation Requirements

Before installing check the minimum hardware and operating system requirements for ODBC. The following are necessary for a successful installation:

  • An Oracle or MySQL installation accessible to the CDS preferably on the same machine
  • An ODBC driver manager
  • An ODBC driver for the data source you wish to access. For example, Oracle in Oracle for Windows or SQL Server

Please ensure the versions are the following or greater:

  • Oracle in Oracle from Oracle Corporation version is 18c
  • MySQL ODBC 8.0 Unicode Driver from Oracle Corporation is version 8.0.16
  • Windows ODBC Data Source Administrator appropriate for your Windows release
  • unixODBC driver Manager 2.3.7 or later

*Cradle install will not work with Oracle databases that have been setup using the ‘Create as Container Database’ option.

ODBC is a licence option which can allow Oracle or SQL or both to work with our Cradle Enterprise version. This new licence is not available for any other version of Cradle. For enquires about the new ODBC licence, please email salesdetails@threesl.com.

Cradle and ODBC

The users can still import and export standard export, CSV, XML and now ReqIF files. If a user is on Windows they can still use our Toolsuite applications. The only difference is the access to databases either directly (DISAM) or through ODBC (Oracle and MySQL).

With Cradle supporting ODBC, a user can now install Cradle on the same database server farm as the Oracle/MySQL databases. A separate server is no longer required.  Although projects can be on a separate server and linked to the Cradle database using a UNC path e.g. \\hostname\path\projects\mmh1. Click for more information on Storing Project Databases in NAS.

3 different projects on 2 different servers
Cradle About WorkBench UI showing 3 different projects on 2 different servers

Installing ODBC

The CDS requires an installation of ODBC on the same machine for either Linux or Windows. Client machines which don’t have the CDS on them don’t need to have ODBC installed at all.

Linux

If the Linux distribution you are installing on does not have v2.3.7 of unixODBC as a package, then you’ll need to build this from source. You can download and find installing steps for it from http://www.unixodbc.org/download.html. Ensure the user installing is the System Administrator or a user with administrator privileges for installing both ODBC and Cradle.

Check for the following files on your Linux installation:

libodbc, libodbccr and libodbcinst
Necessary files on Linux

Windows

If the Windows platform you are installing on does not have ODBC please install the latest Oracle in Oracle for Windows. You can find installing and upgrading documents for Oracle Database here and select the release you are on from the drop-down.

Certain settings are required to be selected when using Oracle in Oracle. Check and enable or disable the following options in the Oracle ODBC Driver Configuration checking all numbers:

Oracle ODBC Driver Configuration
Oracle ODBC Driver Configuration for Application, Oracle and Workarounds

Turn on the Connection Pooling attributes and use the default options:

Pool Connection settings
Turn on Connection Pooling Attributes

Setting up with Cradle

After installation of both Oracle and Cradle, the administrator is required to check and alter the following files correctly:

  • Support file for the driver when required on Windows usually in ‘Oracle <version>\network\admin’

The following example of a tnsnames.ora file, shows it can have more than one Oracle database location set within it.

tnsnames.ora file
tnsnames.ora file
  • Correctly configure the ODBC file for Cradle in %CRADLEHOME%\admin\db_config\odbc called odbc_config

All options are hashed out in the file until an administrator changes them. All options show an example of what can be entered. This is an odbc_config example for just Oracle on one of our installations.

CRADLE_VERSION = 7.7
#
ODBC_DRIVERINFO = ORACLE
    CONFIG_DIR = 'oracle'
    CHARSET_METHOD = ENVIRONMENT
    CHARSET_VAR = 'NLS_LANG'
    CHARSET_BDY = '.'
    CHARSET = 'AL32UTF8'
    CONNECT_STR = 'DSN=$SOURCE;UID="$USER";PWD="$PASSWORD";'
ODBC_DRIVERINFO = END
#
#
ODBC_DRIVER = ORACLE
    ODBC_SOURCE = 'OracleODBC-18c-ORAC'
    DBMS_NAME = 'Oracle'
    DEFAULT_DB_TABLESPACE = 'USERS'
    DEFAULT_DB_SCHEMA_USE = DEFAULT
    DEFAULT_DB_SCHEMA = 'cradle_prj_$PCODE'
    DEFAULT_USER = 'CRADLE_CDS_USER'
    DEFAULT_PASSWORD = '***'
ODBC_DRIVER = END
ODBC_DRIVER = ORACLE
    ODBC_SOURCE = 'OracleODBC-18c-ORAC12'
    DBMS_NAME = 'Oracle'
    DEFAULT_DB_TABLESPACE = 'USERS'
    DEFAULT_DB_SCHEMA_USE = DEFAULT
    DEFAULT_DB_SCHEMA = 'cradle_prj_$PCODE'
    DEFAULT_USER = 'CRADLE_CDS_USER'
    DEFAULT_PASSWORD = '***'
ODBC_DRIVER = END
  • Correctly configure the file create_CRADLE_CDS_USER in cradle\admin\db_config\odbc\setup_scripts

The default user tablespace and users within your Oracle database need to be set within this file. This is to allow the altering and creating privileges for the users. In our original it has:

  • USER “CRADLE_CDS_USER”
  • DEFAULT TABLESPACE “USERS”

The privilege options in create_CRADLE_CDS_USER should be changed to your own tablespace and user names used in the odbc_config file.

Creating New Projects

Users get the same Cradle interface as before but with a new section it now allows connects to 3 different types of database. The different databases can be created through Project Manager by selecting a different Data Source.

Showing 2 different Oracle databases in Create Project UI
Showing 2 different Oracle databases either can be used

Once a source is selected, a new section allows the default settings from the odbc_config file to be bypassed if required:

""

Projects can be still be created through a command line using c_prj using the new -odbc_src option.

[-odbc_src <odbc_source>
 [-odbc_sch {DEFAULT | DATABASE | NONE | <ODBC schema>}]
 [-odbc_usr <ODBC user>]
 [-odbc_pwd <ODBC password>]]
c_prj.exe -create -code TEST -title "Test Project" -path /home/project/odbc -pid ODBC01 -schema DEFAULT -odbc_source OracleODBC-18c-ORAC -odbc_user -odbc_pwd

Both -odbc_user and -odbc_pwd are left blank so the default user and password from the odbc_config file will be used. They will only be filled when an override is required. When creating a database for Oracle then the -odbc_sch DEFAULT would be used. For an SQL database then -odbc_sch DATABASE would be used.

File Locations

All items requirements, system notes and diagrams etc., will be located in an Oracle database but there are some files that are kept in a project folder like in a DISAM project.

The ‘prj_params’ file can be found in the project folder with a new file called ‘connection_config’. The ‘prj_params’ is the same as before, with all the options for the project schema and user interactions. The new ‘connection_config’ file holds the version, type, database source and odbc schema used. It also holds the User and Password to override the DEFAULT USER / PASSWORD from the odbc_config.

CRADLE_VERSION = 7.7
TYPE = PDB_CONN_ODBC
SOURCE = OracleODBC
USER = *****
PASSWORD = *****
DB_SCHEMA_USE = DEFAULT

The definitions e.g. views, queries and reports etc., are still held in the definitions folder under the different user types. Source and Formal Documents are also held as before in the doc and fdoc folders.

*****NOTE*****

Direct manipulation of data in Cradle’s data files held in DISAM or an ODBC supported database is not recommended under any circumstance. The inherent integrity of the data and its internal relationships can only be maintained by accessing through Cradle’s defined UI, command-line or API tools.

  • We do not provide any information about Cradle’s use of Oracle and
    MySQL other than which we provide in our documentation
  • We do not provide any information or assistance to anyone who is
    proposing to access Cradle’s data that is stored in Oracle or
    MySQL other than through Cradle
  • Anyone who accesses, either read-only or read-write, Cradle data
    that is stored in Oracle or MySQL without using Cradle as the only
    means to access that data, does so entirely at their own risk and
    3SL will not accept any responsibility for, nor provide any
    assistance to, anyone who accesses Cradle data in that way and then
    subsequently finds that their data is no longer accessible through,
    or manipulable by, Cradle
Update:

July 2020 – Directory updated

Posted on

Remote Workers and Cradle – Network Address Translation

Your company is using Cradle, but you’re a remote worker – how do you connect to the Cradle Database Server (CDS)?

With Network Address Translation – the IT administrator, where the CDS is located, can modify their firewall to redirect specific external ports to a local server.

Make a note of the internal IP address of the CDS – we’ll use CDS_IPADDR later in this post to reference this address. (In this test environment it is 192.168.11.168).

Cradle Configuration Changes

As an example of a small Cradle system with 6 users, we can configure the ports file as such.  We’re setting ports for each possible user (6) and an extra – so thats 7 ports in each range. To make it easier setting the firewall rules – so we have less rules to setup, we’ve got all the ports in UDP and TCP specific consecutive blocks, which is different to how we have them in the Cradle Help – https://www.threesl.com/cradle/help/

CDS_UDP_PORT_NUMBER = 23960
TOOL_UDP_PORT_NUMBER = 23961
PRJMAN_UDP_PORT_NUMBER = 23962

CDS_TCP_TOOL_PORT_NUMBER   = 16161
CDS_TCP_PRJMAN_PORT_NUMBER = 16162
UTILITIES_TCP_PORT_NUMBER   = 16163-16169
WBENCH_TCP_PORT_NUMBER      = 16170-16176
PRJMAN_TCP_PORT_NUMBER      = 16177

This ports file needs to be copied to all the clients using this CDS.

Firewall Config Changes

The IT administrator can now edit their firewall rules to redirect the external IP ports to the internal CDS.  As part of these rules they can set it so that only specific remote IP addresses are permitted to access these redirected ports.

I’m using pfSense as the example firewall in this case, and adding separate rules for each Cradle Port.
pfSense Cradle NAT Rules

Through the application of Network Address Translation, the remote worker now uses their locally installed Cradle client installation and talks to the Cradle Database Server, as if it is on the Cradle site’s external IP address – which they need to configure as their CRADLE_CDS_HOST address.

Article Updated

28/06/2021 – Use of port ranges in firewall rules.

Posted on

How do I manage my Linux Cradle server when I have no GUI?

Managing your Cradle server via Command Line

Quite often you may find that the server machine you install the CDS and CWS on may not have a graphic user interface, in this case you can manage your Cradle server via a command line

How to Install a Security Code

The c_config command allows you to update a Cradle Security Code

Format
c_config -i code
Example
c-config -i BWEr-DSWe...

How to Start/Stop/Restart the Cradle Database Servers

The c_start command allows you to start, stop, restart or test the Cradle Database Server (CDS) and/or Cradle Web Server (CWS).

Format
c_start {start | stop | restart | test} {cds | cws | all}
Example
c_start start cds
Variations
CommandResult
c_start startstart cds + cws
c_start start cdsstart cds only
c_start start cwsstart cws only
c_start start allstart cds + cws
c_start stopstop cds + cws
c_start stop cdsstop cds only
c_start stop cwsstop cws only
c_start stop allstop cds + cws
c_start restartrestart cds + cws
c_start restart cdsrestart cds only
c_start restart cwsrestart cws only
c_start restart allrestart cds + cws
c_start testgive process numb of cds + cws
c_start test cdsonly give process numb of cds
c_start test cwsonly give process numb of cws
c_start test allgive process numb of cds + cws

How to Manage Cradle Projects

The c_prj command is used to create, delete, lock and unlock Cradle projects.

Format
c_prj.exe [-create
              -code <projcode>
              -title <project title>
              -path <project location>
              [-pid <project PID>]
              [-schema <schema name>]]
          [-delete
              -code <projcode>
              -password <MANAGER password>
              [-method {all | pdb | reg_only}]]
          [-lock
              -auth <user>,<password>,<projcode>
              [-allow_user <user>]]
          [-unlock
              -auth <user>,<password>,<projcode>]
Examples
c_prj.exe -create -code TEST -title "Test Project" -path /home/apps/temp/projects/test -pid TEST01 -schema empty

Will create a project with a project code of TEST, a title of Test Project in the /home/apps/temp/projects location with a PID of TEST01 using the empty schema.

c_prj.exe -delete -code TEST -password MANAGER PASSWORD -method all

Will delete the TEST project along with the registry entry, database files and directories.

 

Posted on

Backups – Keep Your Data Safe!

Backups are an essential part of implementing any tool, and particularly Cradle. There are two types of backups that you should consider, each with its own strengths.

What Needs to Be Backed-Up?

A Cradle system can contain many databases. Each database is stored in a single directory. Naturally, you will want to backup all, or at least most, of these database directories.

The project register held in the files proj_reg.* in the root of your Cradle installation:

  • Linux: $CRADLEHOME
  • Windows: %CRADLEHOME%

reference all of your databases. If you lose these files, or if they are damaged, you will not be able to login to any of your databases. If this ever happens, contact 3SL as we can rebuild these files for you!).

All information related to a database is stored in that database’s directory. But there is some information that is specific to each Windows/Linux user. This information includes the users’ preferences, and any Personal scope definitions (queries, views, forms and so on) that they may have created.

The users’ personal information is stored in:

  • Linux: $CRADLEHOME/admin/definitions/personal
  • Windows: %CRADLEHOME%\admin\definitions\personal

You should consider backing these up.

Finally, you may have changed some of the configuration files to configure Cradle for your IT environment. For example:

  • Cradle startup file, cradle.ini, or .cradlerc on Linux
  • CDS and CWS configuration files in the ‘admin’ directory in the Cradle installation on the server: cds_hosts, cds_users, cws_config
  • External Command Interface configuration file, eci_config
  • LDAP and tracing configuration and options files, help in directories called ldap and trace

You may decide that it is easiest to simply backup the entire admin directory and the Cradle startup file in the executables directory.

You should backup all of these files. If you ever need to re-install all of Cradle, then it is easy to use the backup of these files to restore all your configuration work.

Types of Database Backup

There are two types of database backup:

  • Image backups, that simply backup the database’s directory, containing all of the database tables and definition files
  • Export backups, that perform a full Cradle export on the database, exporting every piece of information into Cradle format. All Cradle versions are guaranteed to be backwards-compatible such that any version of Cradle can import an export file produced by the current version of Cradle, and also any earlier version of Cradle.

We recommend that you run both types of backup.

Image Backups

Image backups are a backup of all of the files and directories in a database.

It is easy to backup your databases if all of the databases have a common root directory. For example, you could store your databases in directories such as:

  • /Databases/Active/Test
  • /Databases/Active/Production
  • /Databases/Active/New-Product

In this case, you could also backup /Databases/Active to backup all of the databases at the same time.

You will already backup information on your servers. So it should be easy to add the Cradle database directories to your existing backup system.

If you want to backup databases directly, then we recommend using tar and gzip on Linux (they are also available for Windows) or either WinZIP or 7-zip on Windows. On Linux, you would use commands such as:

cd /Databases/Active
tar cf test.tar ./Test
gzip test.tar

You may find your system can combine these utilities into one command.

Characteristics

The advantage of an image backup is that it is quick.

The disadvantages of an image backup are that it is impossible to restore an individual item or cross reference from the backup. An image backup contains entire database tables. So the smallest thing that you can recover from an image backup is an individual database table, not an item of information (which is a rows in one or several tables).

Export Backups

Cradle includes a utility called c_io that can perform exports and imports of any, some or all of the data in a database.

For example, the following c_io command will export all of the data in the demonstration database DEMO that is part of all Cradle systems:

c_io -login MANAGER,MANAGER,DEMO -export /tmp/export.exp -type all

You can perform incremental exports using options:

  • -from yyyymmdd
  • -to yyyymmdd

You can also use the -log option to produce a log file that summarises everything that has been written into the export file.

Characteristics

The disadvantage of an export backup is that it is slow.

The advantage of an export backup is that you can restore any single item or cross reference or definition file from the export.

Resilience and Data Integrity

Of course, you should ensure that your backups are stored on a different server to the server that runs Cradle. Ideally, you should have off-site backups as well.

For those of you who trust your data to third parties, you can store it on a remote server… there are many so-called ‘cloud’ services available.

If you decide to use a third party, please check their terms and conditions. For example, DropBox claims intellectual property rights over everything that you deposit with them. This is not a good idea for your company’s private data!

Backup Frequency

We recommend that you run:

  • Image backups twice each day. Take the first backup at lunchtime, to capture the work that everyone has done in the morning. Take the second backup in the evening, to capture the work that everyone has done in the afternoon.
  • Export backups once each day. You can run the export backup in the evening when no-one will be working.
  • Image backups of the administration files every day, or every week. They are small and the backup will run very quickly.
Posted on

How do I fix CDS connection errors?

Diagnosing CDS connection Errors

If you receive a CDS connection error when starting a Cradle tool, the following steps will help you diagnose the most common CDS connection errors and show you how to resolve them. These errors are highlighting a communication problem between the client tool (e.g. WorkBench, Document Loader or Document Publisher) and the Cradle Database Server (CDS). There are four main possible causes ;

Error message saying Could not connect to CDS
Can not connect to CDS error dialog

1 – The CDS is not running.

  1. The CDS is on the same machine as the client, (e.g. Single user products or Cytrix installations) . Run Project Manager to see if the CDS is running or look in the process list (Task Manager on Windows, or ps Process List on Linux)  for  crsvr.exe.
  2. The CDS is running on another machine
    1. In the same TCP/IP subnet (e.g. usual client/server Enterprise installation) . Start Project Manager and look for the CDS.
    2. Another subnet. Login to that machine and look for it in the process list or contact the administrator of that other machine.

Solution – Start the CDS on the machine where it is to run,  by starting Project Manager and starting the CDS. Or at a Linux command prompt

c_start start

If the CDS will not start and is not returning any messages then open a command prompt and perform the following dependant on platform

Windows

Type the following in a command prompt

cd %CRADLEHOME%\bin\exe\windows
crsvr.exe

Linux

Type the following in a command prompt on Linux 32 bit;

cd $CRADLEHOME/bin/exe/linux-ia32/
./crsvr

Type the following in a command prompt on Linux 64 bit;

cd $CRADLEHOME/bin/exe/linux-x86_64/
./crsvr

2 – CDS is running but the Cradle tool is not communicating with it.

Check the CDS is running on a different PC but your Cradle system is set to standalone.

Look for an environment variable called CRADLE_STANDALONE and if it exists either delete it or set its value to false.

Then look in the startup file for the variable STANDALONE and ensure that it is set to false.

3 – The Cradle tool is trying to communicate with the CDS, but its communications do not reach the CDS.

Check that there is evidence that the Cradle tool’s messages are reaching the CDS. To do this, look at the file cds_access.log on the machine running the CDS. There is one multi-line entry in this file for every connection attempt that the CDS receives. If the Cradle tool’s attempt to connect to the CDS reaches the CDS, it will be in this file. Make a note of the last entry in the file, then close it and attempt  to start the Cradle tool. Look at the cds_access.log file again and see if a new entry has appeared at the bottom of it. If not, then the Cradle client’s attempts to connect to the CDS are not being received by the CDS.

If the CDS runs on a machine in another TCP/IP subnet to the PC where the tool is being run, define an environment variable called CRADLE_CDS_HOST whose value is the TCP/IP address or hostname of the machine running the CDS. Run the tool again and look for an entry appearing at the bottom of the cds_access.log file. If the CDS runs on a machine in the same TCP/IP subnet to the PC where the tool is being run, look for the CRADLE_CDS_HOST environment variable and check that its contents are correct. You can delete the variable if this CDS is the only CDS running in the subnet.

Ensure the correct ports are opened on your firewall, the specific ports can be edited from the ports file.

4 – The Cradle tool can communicate with the CDS, but the CDS is ignoring it.

On the machine running the CDS check the cds_hosts file. This file has to either be empty ( all clients are allowed to be connected to the CDS) or it contains a list of IP address / machine names allowed/disallowed to connect to the CDS.

Posted on

Cradle Database Server – CDS Status to 3SL Support

How do I provide CDS status to 3SL support?

If you need to provide information about your Cradle Database Server CDS status to 3SL support you can generate a report from within WorkBench.

If asked to provide information about your current client or server installation, this can be obtained through the The Cradle 'about' or extra information icon ‘About’ button. The resulting screen gives a lot of information about the running system. Additional information for the current ‘Resources’ being consumed by the client or ‘CDS status’ are produced with the buttons at the bottom of the dialog.

Triggering the cds status report
CDS status report

Cradle the Requirements Management and Systems Engineering tool of choice provides full support* to all our Enterprise customers under their maintenance agreement.

Other support options include a large collection of online resources or search the blog’s hints and tips or faq sections.

To contact support, find your local distributor or contact 3SL UK

*Installation support is provided for all our single user configurations. Out of maintenance support must be discussed with our sales team.

Posted on

Safeguarding Against Unintended Data Loss

Your project’s data is important and obviously you do not want to lose or damage any of it.

We recommend the following steps to help guard against accidental deletions of, or damage to, your project data:

  1. Turn on the ‘Enable recovery of deleted items’ option in your schema. Doing so ensures that items are only marked ‘recoverable’ when you delete them. So they can be restored if their deletion was a mistake.
  2. Enable change histories for items wherever possible. Doing so ensures that when cross references are deleted. The items at both ends of the link will have entries added to their change histories recording the deletion of the link between them.
  3. Do not grant BASELINE_RW or ACCESS_BYPASS privilege to any user unless it is absolutely necessary. In general, it is preferable to use the user profile MANAGER for operations where these privileges are needed, rather than to give them to a user who can use them at any time.
  4. Avoid using the MANAGER login account whenever possible. This user profile has all privileges and maximum security clearance. Therefore, you can ANYTHING when logged-in with this user profile, including deleting everything in your database!
  5. Create a separate administrative account, perhaps called MGR, ADMIN or ROOT, and give this account all privileges except ACCESS_BYPASS and BASELINE_RW
  6. We recommend not giving the delete privilege to every user

Safeguarding Against Unintended Data Loss

Article updated 05/12/2018 – Added recommendation to not give every user delete priv
Posted on

Contents of a Cradle database

Each Cradle database contains different sets of information. These can be imagined as layers, where each layer uses the data in the layers below it. For example, cross references cannot exist until the items exist whose relationships are shown by the cross reference. These layers are, highest to lowest:

1. Cross references – the links between the data
2. Items – the data
3. Definitions – how to find, view and report the data
4. User profiles – who can own and access the data
5. Schema – the structure of the data
Cradle database layers
You can export/import each layer individually, or in any combination, or all layers. You should only import a layer of information if the lower layers already exist in the database (unless you know that it is safe).

To initialise a new database from an existing database, you need as a minimum:

– The schema
– Definitions

User profiles are needed to use a database and may be needed for some parts of the schema (such as workflows and alerts) and definitions (user and personal scopes).