2.2 Using MCheck to Simplify User, Certificate, and Database Management

NOTE:Beginning with GMS 18.4, MCheck is expanded and enhanced to include functionality previously available only in a support tool named dsapp.

The dsapp tool let Micro Focus Support personnel manage multiple users and groups, perform certificate-management tasks without requiring terminal prompt commands, and directly affect the health and content of the GMS databases.

MCheck now makes those popular features available to GW Mobility Service Administrators.

To run MCheck:

In a terminal window on the Mobility server, become root by entering su - and the root password.
Change to the following directory:
```
/opt/novell/datasync/tools/mcheck
```

Run the following command:

python3 mcheck.pyc

The top-level MCheck menu displays:

1 System
2 Users
3 Database
4 Checks & Queries
0 Exit

Select Option:

Access the various MCheck tasks by typing numbers to navigate the menu structure shown in the left column of Table 2-1 below.

The right column outlines what MCheck does when the task number from one of the options below is entered:

Table 2-1 Navigating and Using the MCheck utility

Task Navigation Path			Steps and/or Results - log file path is /opt/novell/datasync/tools/mcheck/logs
1. System			Typing 1 exposes the system integrity checks and SSL/TLS certificate-related maintenance tasks explained below.
	1. Get Mobility Configuration		This option Retrieves and checks GMS Configuration settings. Records the settings in the following log file: Log file name: mobConfiguration_yyyy-mm-ddThh:mm:ss.log
	2. GroupWise System Address Book Check		This option Analyzes the accuracy and integrity of the GroupWise System Address book. Reports any problems found in the following log file:. Log file name: sab_yyyy-mm-ddThh:mm:ss.log Recommends corrective action if needed.
	3. SSL Check		This option Assesses whether the GMS server and its associated POAs are ready for SSL/TLS certificate verification, by checking the following The Mobility Default POA is a host name. The associated Mobility POAs are host names. The Mobility default POA uses SSL. The GMS server has a valid Mobility Certificate Store (/var/lib/datasync/mobility/mob_ca.pem. The Mobility Default POA certificate can be verified. The associated Mobility POAs’ certificates can be verified. Logs the results and recommends corrective action if needed: Log file name: sslCheck_yyyy-mm-ddThh:mm:ss.log
	3. Fix Mobility Encryption (Conditional - appears only when the hostname changed and GMS requires fixing)		IMPORTANT:If you change the GMS server’s host name after installing and configuring GMS, for example as part of an upgrade process, encryption breaks and GMS stops working. When that happens, only a restricted System is available with two options: 1. Certificates 2. Fix Mobility Encryption. To repair GMS, do the following: Type 2. Enter the old host name or the server. MCheck stops GMS and Mobility. Then it updates and fixes various configuration files. And finally it prompts whether you want to start Mobility services. Enter y, the service restarts, and you are prompted to press Enter again. Mobility encryption is now fixed, and the next time you start MCheck, the standard options appear. Type 0 twice to exit MCheck. Log file name: fixHostname_yyyy-mm-ddThh:mm:ss.log
	4. GroupWise Maintenance Verification		This option Verifies that the GroupWise license is current and other associated data is correct. Logs the results and recommends corrective action if needed. Log file name: GWLicenseCheck_yyyy-mm-ddThh:mm:ss.log
	5. Certificates 1. Certificates (This becomes the first option if Mobility Encryption requires fixing.)		Provides guided certificate generation and maintenance tasks as documented below.
		1. Generate CSR & Private Key	Guides you through the process of generating a private key and creating a Certificate Signing Request (CSR) to submit to a trusted third-party Certificate Authority. This option Lets you generate a private key as follows: Asks that you specify where to store the key. If the path doesn’t exist, you can have MCheck create it. Prompts you to enter and confirm a password for the key file. When the password is confirmed, generates an RSA private key. Prompts you for the information needed to generate a Certificate Signing Request (CSR): MCheck prompts for all the fields in a standard request, but only the following four are mandatory: Country: This is your country’s two-digit country code. For example. US for the United States, IN for India, JP for Japan. State or Locality: This is the full name of the state or locality. For example, California or Barcelona. Organization Name: This is the full legal company or personal name as registered in your locality. Common Name: This must be the fully qualified domain name (FQDN) of the system this certificate will secure. For example gms_01.servers.example.com. When you have entered the information, MCheck displays the paths and file names of the Private Key just generated and the CSR file. Then it prompts whether you want to generate a self-signed-certificate from the CSR just created. We strongly recommend that you Answer n to all of the prompts that follow. Obtain a third-party-certified public certificate by submitting the CSR just created to one of the reliable Certificate Authorities on the web. When you receive the third-party certificate, continue with 3. Apply certificates (Generate PEM). WARNING:If you answer y to the prompt, MCheck generates and installs a self-signed certificate. This poses a security risk and is not recommended. If you must use a self-signed certificate temporarily, replace it as soon as possible.
		2. Generate self-signed certificate	Although not recommended as a best practice, this option lets you generate a self-signed certificate from a previously created CSR. For example, the CSR that you created in 1. Generate CSR & Private Key. You must specify The path to where the CSR and private key are located and what they are named. (You can list the files in the specified directory if needed.) How many days you want the self-signed certificate to be valid for. A passphrase for the key. MCheck signs the certificate and then prompts whether you want to apply the certificates (generate a PEM file). If you type y, MCheck prompts for the key’s passphrase (just entered above). MCheck verifies the passphrase and then asks whether to apply the self-signed certificates (generate a PEM file). If you type y, MCheck again prompts for the key’s passphrase. MCheck verifies that the certificate and key pair match and asks whether there are previously generated intermediate certificate files or bundles. After following the prompts, the self-signed certificate is applied.
		3. Apply certificates (Generate PEM)	After you receive the signed public certificate from a certified CA, use this option to apply the certificates by following the prompts as briefly explained below. Specify the location of the working directory where you have copied your Private key file, the Public certificate that you received from the CA, and any intermediate certificate files or bundles that you want to include in the certificate store. For example, /root/Downloads/pub. List the files in your working directory so you have their exact names. Specify the name of the Private key that you created in Generate CSR & Private key.. Specify the name of the Public certificate that you received from the third-pary CA. Enter the pass phrase for your Private key, two times, as prompted. MCheck verifies that the Public certificate and Private key match. If you need to include any intermediate certificate files or bundles in the certificate store, answer y to the prompt and enter the name of an intermediate certificate (.crt file) or bundle (.pem file). Repeat the previous step until all of your intermediate files and bundles are entered. Then answer n to the prompt. Enter the pass phrase for the Private key file for the third time. MCheck then creates the gms_mobility.pem file in your working directory and displays its location. IMPORTANT:When MCheck Generates the PEM, it removes the key passphrase as required for seamless access by mobile devices. Enter y to install the PEM certificate store.
		4. Verify certificate / key pair	Use this option if you simply need to verify that a certificate and key pair match.
		5. Update GMS Services certificates	GMS services rely on an internal certificate store named gms_server.pem. You must never manually change or modify this certificate store. On the other hand, the certificates eventually expire. When that happens, use this option to update the certificates and renew the gms_server.pem certificate store.
		0. Back to System Menu
	0. Main Menu

2. Users			Typing 2 in the main menu, exposes the user and group tasks explained below.
	1. Check User		Use this option to view the GMS statistics for a given user, discover any problems with the account, and see what actions will correct the problems. MCheck prompts you to enter the GroupWise User ID: It then displays the user that you specifed and reports statistics, problems found, and any actions required Press Enter to continue. Log file name: GWuser_id_yyyy-mm-ddThh:mm:ss.log NOTE:You can also run Check User directly from the command line without accessing the menu by running the command: python3 mcheck.pyc --user userID
	2. Remove Old Event Configurations		Use this option to remove all event configurations that contain the MAC address that you enter. MCheck displays a brief summary of the action to be taken, followed by the Mobility server’s MAC address as a Hexidecimal number. Type the server’s displayed MAC address and press Enter. MCheck then Checks each user. Removes event configurations that contain the Mobility server MAC address and logs the actions taken in Log file name: removeEventConfigurations_yyyy-mm-ddThh:mm:ss.log Press Enter to return to the Users menu.
	3. Remove and reinitialize users options
		1. Force remove user(s)/group(s) db references	GMS uses databases to track which GroupWise users are registered for Mobility services and the data and messages, etc. that are associated with them. If you are unable to remove users or groups using the Web Console, you can use this option to force the removal of users and/or groups from the databases. Users, groups, and data on the GroupWise system are not affected. MCheck prompts for a comma-delimited list of user and/or group IDs. NOTE:The process doesn’t provide lists to pick from; you must manually enter each ID. MCheck displays the issues discovered on the screen along with the action recommended to resolve the issue. For example, you might need to restart GMS to complete user and group removal. Log file name: userActions_yyyy-mm-ddThh:mm:ss.log
		2. Reinitialize user(s)/group(s)	If one or more of you Mobility user accounts has problems, for example they are missing calendar or other data, MCheck can clear their data and messages and then restore everything from the backend GroupWise system. MCheck prompts for a comma-delimited list of user and/or group IDs. NOTE:The process doesn’t provide lists to pick from; you must manually enter each ID. MCheck clears all data associated with the IDs you have entered and then reinitializes the accounts. Log file name: userActions_yyyy-mm-ddThh:mm:ss.log
		3. Reinitialize all failed users	If multiple Mobility users show a Failed state in the admin console, you can use this option to reinitialize all of them rather than using the admin console to reinitialize one of them at a time.This removes associated data from the database and synchronizes with GW again. Log file name: userActions_yyyy-mm-ddThh:mm:ss.log
		4. Reinitialize all users	IMPORTANT:If you choose to continue after the initial prompt, this will take some time to complete. Also, a device configured with a user being reinitialized will be unable to connect to the server until that user is reinitialized. MCheck prompts whether you want to continue. Enter y to continue or n to return to the Remove and Reinitialize Users Options menu. Log file name: userActions_yyyy-mm-ddThh:mm:ss.log
		0. Back to System Menu
	0. Main Menu

3. Database			To enter the Database sub-menus, you must stop Mobility. MCheck prompts you as follows: Stop Mobility Now [y/n] If you type n, MCheck returns to Main Menu.
	1. Vacuum Database		Consider using this option when your mobility databases seem larger than expected. Vacuuming a database tightens up data records, making previously used space fragments once again available for database use. Although PostgreSQL includes a process that performs incremental vacuum operations, these are not as thorough as a full vacuum. This option performs a full vacuum of the mobility databases. You should follow this up with next Database option to re-index the database. Log file name: dbActions_yyyy-mm-ddThh:mm:ss.log
	2. Re-index Database		If users are experiencing performance delays, reindexing the database might help. This options rebuilds all of the indexes. Keep in mind that reindexing can take a while if the Mobility databases are large. Log file name: dbActions_yyyy-mm-ddThh:mm:ss.log
	3. CUSO (Clean-up Start Over
		1. Cleanup and Start Over (Except Users)	This removes everything from the mobility databases except the User and Group records, which are reinitialized when the cleanup process concludes. Log file name: dbActions_yyyy-mm-ddThh:mm:ss.log
		2. Cleanup and Start Over (Everything)	This removes everything from the mobility databases, essentially restoring the mobility server to where it was when the initial install completed. Log file name: dbActions_yyyy-mm-ddThh:mm:ss.log
	4. Change PostgreSQL datasync_user password		This option enables you to change the password for the datasync_user account in the event of a lost password. The datasync_user account is used to access the PostgreSQL databases for the GroupWise Mobility Service.
	0. Back		Because MCheck’s database operations required stopping the service, you are prompted as follows: Do you want to restart Mobility now? [y/n]If you type y, Mobility restarts and MCheck returns you to the Main Menu. If you type n, MCheck returns to Main Menu without restarting Mobility. As a result, Mobility services are not available to users and some MCheck operations fail until Mobility is restarted.
4. Checks & Queries			Typing 4 in the main menu, exposes the checks and queries explained below. If you detect any unresolvable issues from running any of these checks, contact Customer Support.
	1. General Health Check		The General Health Check runs and displays a series of tests that populate a status in the terminal. After all the checks are run, you can view more detailed information about each check in the mcheck logs at: /opt/novell/datasync/tools/mcheck/logs To find issues in an open log, search for /Failed. NOTE:You can also run the General Health Check directly from the command line without accessing the menu by running the command: python3 mcheck.pyc --healthCheck HINT:The first time this option is run, the gh.conf file is created in the /opt/novell/datasync/tools/mcheck/conf directory. This file is used for the NTP server time check. If you are getting an NTP failure when running the General Health Check, you can modify the file to point to a different NTP server.
	2. GW Pending Events by User (consumerevents)		This option displays data about events that users execute on their devices that are pending processing in the mobility service.
	3. Mobility Pending events by User (syncevents)		This option displays data about user events driven by the mobility service that have not yet synced with user devices.
	0. Back
0. Exit			Return to the terminal prompt.