“Don't crack up, bend your brain, see both sides. Throw off your mental chains.” Folks we have a new command line utility for GroupWise! For those that love command line, you will love this one. For those that wonder 'What happened to all the GUI we used to have?' Sorry, I can sympathize. But just wait til you see what can be done! This article will focus solely on the GroupWise Administration Utility (GAU) aka. gwadminutil.
First before I dig in to the GAU, let me take a moment to explain and show what options for maintenance are available today in GroupWise 2014 GAC (GroupWise Administration Console).
When you are in the domain page of a domain, one of the buttons that can be selected is 'Maintenance'. Once selected, a popup Domain Database Maintenance window will show up. There are only 5 options that can be run from here:
That's it. Missing here especially is 'Synchronize' where many are use to synchronizing a primary with a secondary domain. The other most often used option is 'Rebuild'. Both are now wrapped up into the gwadminutil.
Figure 1: GAC: Domain Maintenance Options
In the case of a post office, once in the post office page again there is a 'Maintenance' button that can be selected. Once selected a popup window appears listing the following options:
Unlike the domain maintenance, these are the most often used listed here. The gwadminutil is less about the post office and more about system or domain level maintenance. Certainly that will ease the transition for most administrators.
Figure 2: GAC: Post Office Maintenance Options
The GroupWise Administration Utility (GAU) or gwadminutil, as the actual command is typed, script is located in the /opt/novell/groupwise/admin directory. Thoughtfully, the GroupWise Dev team has made it so that we can run gwadminutil from anywhere in a path on the linux server. So you do not have to be in the root where the script is located to run it.
GroupWise Dev team has also provided 'man' pages for the gwadminutil. I highly recommend either once upgraded to GroupWise 2014 or preferably in a lab setting, you spend some time reading the 'man' pages and tinkering with the gwadminutil. It's highly likely you will need to use it. I have used them in order to write this article, and do borrow from them as well for syntax and demonstration purposes. To access the gwadminutil 'man' pages, in a terminal window type:
man gwadminutil
At this point, a type on the RETURN key will take you down the 'man' pages one line at a time. Using the down/up arrow keys will allow you to move forward and back through the 'man' pages. And to quit the 'man' pages type: q . The syntax in using the gwadminutil is standard linux. Here is a the syntax:
gwadminutil option arguments
To get the proper syntax for the command along with its arguments and examples type:
gwadminutil option
Figure 3: gwadminutil Options
Note: To stop the gwadminutil from running, a CTL-C will stop it. As to whether that is good to do in the middle of a process, I cannot say and will leave it to the GroupWise Dev and Support team to say.
gwadminutil Options:
There are 17 different options that can be run from the gwadminutil. Each has its own set of syntax when running them. Many are familiar friends and a few are brand new. Several of these are not available in the GroupWise Admin Console and can ONLY be run from the gwadminutil. Let's take a look at these commands.
Novell classifies the commands into 3 categories. They are:
At this point, I will drill down into these options. My focus will be on the most commonly used options and present examples. Others I will just provide syntax. Pictures will be used in most all cases so as to show real examples. (And to save my fingers from typing.) Hopefully by the end of this article you will have a better comprehension of the utility and it will make using it easier for you. And away we go!
This is the simplest and more familiar of the options. Always recommended to run this first if you sense there may be issues with a domain or post office.
Figure 4: gwadminutil validate syntax
Figure 5: gwadminutil validate /path-to-database
As you can see the validate checks the records and also reclaims space that is unused, providing a simple report.
A Recover can be run with the agents running against the database. So no agent stop needed here. It will fix issues found. Its great for fixing some issues mid-day. I use this before I upgrade a domain or post office as well. And on the occasion when an upgraded domain or post office does not appear to upgrade the version, I will run a recover. That usually gets it. The syntax is simple as shown below.
Figure 6: gwadminutil recover syntax
Figure 7: gwadminutil recover /path-to-database
Of course in the process of running the Recover, you must point to the local path for the database you want to recover. Mind you this can be the same location as the production domain/post office. Or, it can be a temporary location. If a temporary location is chosen, you would have to copy the recovered database to the production location.
On occasion, I have seen very large domain and post office databases. This is usually when a customer has not run some maintenance on them. Typically, as we saw in the Validate, a reduce of the database size will take place using reclaim. Reclaim allows for the reduction in space within a database. You may ask 'Why does the database have space in it?' . Whenever there is a change to a system, domain or post office, that change is written to the database. And of course that expands the database. And sometimes, things are removed as well from systems, domains and post offices. The databases do not shrink on a remove. Hence the Reclaim function.
Figure 8: gwadminutil reclaim syntax
Figure 9: gwadminutil reclaim /path-to-database
As you will note here, you must run the Reclaim and then provide the local path to where the database is that you wish to reclaim space on.
Reindexing is very important for proper Address Book functioning. Ever created a new user in the GroupWise system only to have it not show up in the Address Book. Or change the name of a user and it does not change in the GroupWise System Address Book? Run a Reindex and those problems are fixed.
Figure 10: gwadminutil reindex syntax
Figure 11: gwadminutil reindex /path-to-database
As with the others, a path to the database must be provided when running the Reindex. The MTA can be running against the database when a Reindex is run.
We are all very familiar with rebuilds. As such we know we are well advised to take down an agent (MTA/POA) before we do a rebuild 'in-place' when we do it with ConsoleOne. However, with gwadminutil, we can do a rebuild 'in-place' on a local box with the agents running. And it's highly recommended a restart of the agent is performed after the Rebuild is complete. That stated, just because you can, does not mean you should in this case. Best Practice is to take the agent down, rebuild in place, bring the agent back up. An alternative, rebuild in a temporary location, then copy that rebuilt database to the production location after the agent has been taken down. Then of course restart the agent. What is the difference? Time. You could run a rebuild on your domains to a temporary location, then take the agents down, copy the rebuilt database over and bring the agents up. Or in mid-day, the same could be done. In the end, it shortens the outage time.
Figure 12: gwadminutil rebuild syntax
There are 2 rebuild options per se: domain and post office. In the first figure note we use the -d for the path to the domain database, the -n for the name of the domain to be rebuilt and -o for the path to where we want to place the rebuilt database. This last one could be the same directory in the -d or it could be in a temporary location.
Figure 13: gwadminutil rebuild -d /path-to-domain -n name-of-domain -o /path-to-place-rebuilt-db
In this next figure we rebuild a post office. As you note, the -d is pointing to the path of the parent domain while the -n is the name of the post office being rebuilt. Finally the -o points to the path where we want the rebuilt database to be placed. Again, it could be the original post office directory or a temporary location.
Figure 14: gwadminutil rebuild -d /path-to-domain -n post-office-name -o /path-to-place-rebuilt-po-db
I highly recommend as part of the upgrade of GroupWise to 2014, a test system be built for practice and testing of course. And as stated, for some of the GroupWise Maintenance options, command line must be used. Better to learn in a test system then in a production one.
Sync is another process we are familiar with as well. This option synchronizes the Primary domain with a secondary domain. This option is used often when domain records get out of sync, or as a pre-cursor to a promote of a secondary to Primary, a merge or a release of domains. Suffice to say its often used. It is very simple to use with the -p used for the path to the primary and the -d the path to the secondary domain. Now if you have domains on separate servers, a likely placement, a mount of the secondary's disk to the Primary's server will be needed.
Figure 15: gwadminutil sync syntax
In the case of my demo system I have 2 domains on the same server making this and really most of the options ease to run. Not a normal setup in most GroupWise systems for sure. The really nice part of this 'sync' versus the older GroupWise versions is that you get to see what records it is synchronizing. A lot more detail and information.
Figure 16: gwadminutl sync -p /path-to-primary -d /path-to-secondary
The Convert option is used to promote a secondary domain to primary domain. Again if you have both domains on separate servers you will have to mount the respective disk before running this option. The syntax is very easy as well. Using the -p for Primary domain path and the -d for the secondary domain path. When you run this option, there will be no reporting as we have seen in the others. It simply returns a cursor. However, when you look in GAC, you will see the tell tale 'red carpet' under the secondary you just promoted to Primary.
Figure 17: gwadminutil convert syntax
Figure 18: gwadminutil -p /path-to-primary -d /path-to-secondary
In the past often times I would use this option as part of a GroupWise fix of corrupted databases. But now I need to think it through a bit further. Here is why. New is GroupWise 2014, the Primary domain is also a Certificate Authority for GroupWise. That means if promoting a secondary to Primary, its a must to change the CA to the newly promoted Primary domain. This assumes long term promotion of Primary domain, not short term. Meaning, if you plan to do any sort of administration a new CA will have to be created. If on the other hand for whatever reason, the secondary was converted for a temporary reason, likely no change to the CA needed if the original Primary is converted back.
The Release option along with Merge are used very infrequently. However, when the time comes, the gwadminutil will have to be used. This option has the standard -p and -d but also adds a -n. The -n is for the name of the new GroupWise 2014 system created upon the release of the domain. Order counts as well with the -d for the domain being released going first.
Figure 19: gwadminutil release syntax
As you can see in the figure below, syntax is simple enough and assuming no issues with your GroupWise databases, the release takes place quickly. In the example below, I released my PODOM which had a post office under it as well. A nice feature after the release are the additional tasks list provided. This list is great to help you finalize the release.
Figure 20: gwadminutil release -d /path-to-domain-released -p /path-to-primary -n Name-of-New-System
A final note here. Once you have released the domain, if you go to your GAC and login, the domain released will show as a External GroupWise Domain. It will be white/black in color just like seen in other version of GroupWise.
Much like the Release option, the merge is often not used but when it is used, gwadminutil will be there for you. The order using the -d switch for the domain being merged into the -p GroupWise system Primary domain are both followed by a -mergesync. The -mergesync is as it states, a synchronization of information of the external domain. A simple option again assuming no issues with the domains involved.
Figure 21: gwadminutil merge syntax
Figure 22: gwadminutil merge -d /path-to-domain-to-merge -p /path-to-primary -mergesync
Once the merge is run, a long report will be produced. It will show all the records being synchronized and will replicate records as well. Also, additional tasks are provided to finalize the merge process. These tasks install the certificates to the new domain and post office merged into the GroupWise system.
Figure 23: After Merge Tasks
As you can see the after merge task downloads a certificate from the CA, generates a CSR, requests a certificate from the CA and then stores it. So all that manual work is now done for you!! We will cover the 'certinst' further in the article.
Setadmin is a new feature that creates a new GroupWise 'superuser' Administrator. As stated, when creating a new GroupWise 2014 system or on an upgrade a new 'superuser' is created. Now in the case the superuser created is lost or a password must be changed, this option will do it. Mind you this is a system-level administrator. The -d is used for the path to the database, Primary, along with the -a for the name desired for the admin and the -p for the password.
Figure 24: gwadminutil setadmin syntax
Figure 25: gwadminutil setadmin -d /path-to-primary -a name-of-admin -p password-for-admin
When running this utility there is no report back but for a cursor. The way to verify/test is to login to the GAC with the old admin and password, it should be denied. Then login with the new admin and password.
The upgrade option will upgrade a domain or post office on a server. In order to use this option the GroupWise Server (rpm's) will have to be installed from the code using the 'install.sh'. Then running this will upgrade the databases. This will be a great option for two events.
It should not be used for an upgrade to GroupWise 2014 because there are several items, like superuser, GAC, etc. that must be set up using the install.sh for GroupWise 2014. Also it should be stated an upgrade can only take place on the server where the gwadminutil is run. By this I mean, you could not mount another server disk and run the gwadminutil upgrade to upgrade domains/post offices on a different server.
Figure 26: gwadminutil upgrade syntax
WARNING: TREAD LIGHTLY with this option. You can cause a communication interruption of the GroupWise system if you run the CA option with certain switches.
Now we get into the more robust and new offerings of the gwadminutil. GroupWise 2014 is different in several ways than any previous version. The first being now by default all agents are secured with SSL and that requires certificates. Enter the new Certificate Authority (CA) for GroupWise 2014. The Certificate Authority is part of the GroupWise Admin Service (GAS) which is the engine of the GroupWise Administration Console.
The GAS CA issues self-signed certificates for servers holding GroupWise agents/databases like MTA/Domain and POA/Post Office. GWIA as well. The most important of these is the Primary domain server. The certificate issued to that server is the one that signs all other certificates for GroupWise servers. This is important to note for two reasons.
The ca option allows various activities from generating new certificate to revoking a certificate. This is one of the options I would recommend using a test GroupWise 2014 system to play with so you understand the process but also the affects. For the article, I will cover a couple of the commands that are less invasive. I will save the others for another article on certificates and GroupWise 2014.
There are several switches to the ca command. The -l , -d and -p are the most likely to be used in a day to day basis. Therefore, I will cover them. The others all require a lot more detail and explanation.
Figure 27: gwadminutil ca syntax
The simplest of the options with ca is the -l. This will show you the certificates outstanding/issued and provide the serial numbers. Lots of good information to be used to revoke, print or otherwise make changes. In the course of using the -l (- - list) switch the -d has to be used to provide the path to the domain.
Figure 28: gwadminutil ca -d /path-to-primary -l
Using the information from the list switch, we can print out details on a certificate with the -p switch. In the figure below, information is provided in depth on the certificate. I am only providing a portion of the output that was provided because the screen shot would have been very large.
Figure 29: Sample: gwadminutil ca -d /path-to-domain -p [serial number of certificate]
Suffice to say, if you run the ca option, it is best to fully understand all the implications and potential events that can be created. This option is one of the reasons I HIGHLY recommend a test/demo GroupWise 2014 system. Better to understand/play on a test system.
The certinst command works in conjunction with the ca command. This command installs new certificates. In this instance, should you need to install a new certificate or you had a failure of certificates, this command will assist with those operations. More to the point, the certinst will request and install a new certificate for the GAS (Admin Service) on other servers. If for whatever reason the certificate on one or more GroupWise servers where domains/post offices exist is not functional or broken, using the certinst will request and install from the CA a new certificate. An example of such a problem would be getting certificate errors when trying to connect to a secondary domain while in the GAC (GroupWise Administration Console).
Figure 30: gwadminutil certinst syntax
The dbinfo option when pointed to a domain or post office path will provide the information as we have been accustom to in ConsoleOne. Great information for troubleshooting, upgrading and just getting very basic information of what is running on a server.
Figure 31: gwadminutil dbinfo syntax
As seen below, this option provides:
Figure 32: gwadminutil dbinfo /path-to-domain (or /path-to-post office
The installcfg command is used for installation authentication. The GroupWise 2014 Installation Wizard by default uses a token for access that is good for 1 hour. Obviously after the time is up or the installation is disrupted, the Installation Wizard/token is terminated. In the wizard a new token can be created. Or the installcfg command as an alternative can be used to set the Installation to use either a token or user id. That said, the installation can also be disabled for each server. I would call that a good security move to make sure no one runs an install unless its needed.
Figure 33: gwadminutil installcfg syntax
The Services switch provides a large list of options from stop/start of services to installing an MTA/POA/GWIA to just listing services. You can also uninstall services as well.
Figure 34: gwadminutil services syntax
Of the options with Services, the -l list feature will be most helpful. It provides you with the services running on the server along with the location of the executable and the location of the startup file. Note in GroupWise 2014, startup files for MTA/POA/GWIA are now stored in their respective directories rather than with the operating system executable locations. The exception is the gwdva which is still stored in the default location of /opt/novell/groupwise/agents/share .
Figure 35: gwadminutil services -l
The Services command does have a short cut command. The short cut command is: gwsc. See the figure below for an example.
Figure 36: Example: gwsc -l (gwadminutil services - - list)
This option simply presents the settings for cluster and default admin port. There are no other attributes or settings that can be set at this time.
Figure 37: gwadminutil config syntax
If you have GroupWise on a cluster then enabling the cluster feature is of course recommended. That command is:
Figure 38: gwadminutil config -cluster ENABLE/DISABLE
If you want to change the default port for the admin service, that command is:
Figure 39: gwadminutil config -defaultport PORTNUMBER
Whoa boy!! That was one long article! I hope it provides you with some good information to help better adopt GroupWise 2014. The gwadminutil is quite a utility with a bevy of optional commands. Again I strongly recommend getting to know this utility prior to upgrading so you can take advantage of its power. This article should help you better understand this very powerful and new feature. Now we can all sing a “New Song” with the GroupWise Administration Utility. Good luck!!
Got comments or article ideas? Need help GroupWise? Drop me a line at: Gregg@HinchmanConsulting.com. "The Force is strong in this one."
Support
Documentation
Training
Partner Portal