domino server controller - domino console

Last edited 7/21/2005 1 ©IBM 2005

Table of Contents

Course Overview ................................................................................................................ 2 Key Points About this Course............................................................................................. 4 Lesson 1: Introduction to the Domino Server Controller and Domino Console ................ 5 Lesson 2: Starting and Stopping the Applications.............................................................. 8 Lesson 3: Entering Commands ......................................................................................... 17 Lesson 4: Using the Domino Server Controller with Partitioned Servers ........................ 20 Lesson 5: Quick Facts and Miscellanea............................................................................ 22 Lesson 6: eSupport Resources ......................................................................................... 24

Last edited 7/21/2005 2 ©IBM 2005

Course Overview

Introduction This course will introduce you to the Domino Server Controller and Domino

Console.

Learning Objectives

Upon completion of this course, you will be able to… • Run the applications with the various startup switches • Connect to the Domino Server Controller from the Domino Console • Exit the Domino Server Controller properly • Issue the various types of commands available using the Domino Console • Workaround a common issue involving partitioned Domino servers • Identify the steps to install the Domino Console on a non-Notes machine • Identify the necessary Notes account credentials to administer a server from

the Domino Console • Identify the configuration files (.ini files) for the Domino Server Controller

and Domino Console • Identify knowledge resources for the applications

In this Course This course is divided into the following lessons:

Lessons See PageLesson 1: Introduction to the Domino Server Controller and

Domino Console 5

Lesson 2: Starting and Stopping the Applications 8 Lesson 3: Entering Commands 17 Lesson 4: Using the Domino Server Controller with Partitioned Servers 20

Lesson 5: Quick Facts and Miscellanea 22 Lesson 6: Resources 24

Continued on next page

Last edited 7/21/2005 3 ©IBM 2005

Course Overview, Continued

Timing The timing of this courses components are as follows:

Component Approximate Time Course Overview 5 minutes Lesson 1 15 minutes Lesson 2 45 minutes Lesson 3 35 minutes Lesson 4 15 minutes Lesson 5 10 minutes Lesson 6 10 minutes Total: 2 hours 15 min (approx)

Last edited 7/21/2005 4 ©IBM 2005

Key Points About this Course

Prerequisites This course assumes that with product documentation, you are able to install,

configure and use the following: • Notes Client • Domino Server

Course Format This course's design enables it to be either delivered in a classroom setting (in

which the instructor's role is primarily facilitation) or taken as a self-paced course by an individual participant.

Requirements To complete the all of the exercises and activities, you will need the

following: Hardware • One machine that has Domino installed on it. This machine will be referred

to in this course as the “server machine.” • One machine that has a Notes client installed on it. This machine will be

referred to in this course as the “client machine.” Software • Notes client and Domino server install code Documentation • Lotus Software Knowledge Base: https://www-

927.ibm.com/search/SupportSearchWeb/SupportSearch?pageCode=SBS&brand=lotus

• Domino Administrator Help (use the latest version available) • Domino Console online help • The documentation can be obtained here if you need to get it:

http://www-10.lotus.com/ldd/doc Other • You will need a Person document on your Domino server that has an

Internet password and whose account is designated as a Full Access Administrator in the Server document

Last edited 7/21/2005 5 ©IBM 2005

Lesson 1: Introduction to the Domino Server Controller and Domino Console

Introduction Beginning in Notes/Domino 6, two Java-based applications became available

for running and administering a Domino Server: the Domino Server Controller and Domino Console. These applications can be used as an alternative to the “traditional” Domino server and Domino console.

Nomenclature Madness

In the Help, Release Notes, and Knowledge Base these applications are referred to intermittently as “Server Controller or Domino Controller and Domino Console.” Many times the terms used to identify these applications are further distorted. Terms such as “Java Console, Java Server, Java Controller,” etc., are commonly used. When you have completed this training, you should be skilled in asking the right questions to help you determine exactly what application is in question. To avoid confusion between these Java applications and the “traditional” Domino server and Domino console, they will be referred to in this training document as “Domino Server Controller, Domino Server, and Domino Console.” Note the proper case - - when you see these terms in proper case, we are referring to these Java applications and a Domino Server running under the control of the Domino Server Controller.

Domino Server Controller The Domino Server Controller is a Java-based program that controls a

Domino Server. In this sense, administrators will often say they are running a Domino server “under the Domino Server Controller.”

When a Domino Server runs under a Domino Server Controller you can send Domino server commands, Controller commands, and shell commands from any of the following consoles: the Domino Console, server console in the Administrator client, or the Web Administrator.

By default, the Domino Server Controller listens for connections over port 2050.


Last edited 7/21/2005 6 ©IBM 2005

Lesson 1: Introduction to the Domino Server Controller and Domino Console, Continued

Domino Console The Domino Console is the Java-based console that you can use to

communicate with a Domino Server Controller (and the Domino server it controls). When you connect to the Domino Server Controller from a supported console, it looks like the familiar “traditional” Domino server console with the addition of a GUI menu. With its GUI features, it is similar to the remote console in the Domino Administrator Client. The Domino Console functions strictly as a server console. In fact, you can think of it as a “thin” remote server console client. It does not include the full set of Domino administration features available through the Domino Administrator and Web Administrator clients. For example, you cannot use it to open and manage Notes databases. When you run a Domino Server Controller, you no longer have access to the traditional local server console. You can communicate only through the Domino Console or a console in the Domino Administrator or Web Administrator clients.

Note: To use the Domino Console to communicate with a Domino Server, the server must be running under a Domino Server Controller.

Key Concept It is important to understand that the Domino Server Controller can run by

itself, without a Domino Server running under it. When running in this manner, you can connect to the Domino Server Controller with the Domino Console and issue commands that are specific to the Domino Server Controller. These commands are referred to as “Controller commands.” This concept will be reinforced as you progress through this course


Last edited 7/21/2005 7 ©IBM 2005

Lesson 1: Introduction to the Domino Server Controller and Domino Console, Continued

Domino Console Advantages

The Domino Console has many advantages: • You can run the Domino Console on any platform except Macintosh • You can send commands to multiple servers simultaneously • It doesn't require a Notes ID, only a Person document with an Internet

password, so you can connect to servers certified by different certifiers without needing multiple Notes IDs or cross-certificates

• You can customize output to the Domino Console, for example, use local event filters to specify the types of events the Domino Console displays.

• You can also log server output to log files • You can send commands other than standard Domino server console

commands, such as: • Shell commands (OS commands) • Controller commands

Note: some of the advantages listed above are also available in the Web Administrator and the remote console in the Domino Administrator client.

Installation The code needed to run the Domino Server Controller (and underlying

Domino Server) are provided with Domino. The code needed to run the Domino Console are provided with Domino, the Notes client, and the Domino Administrator client.

Last edited 7/21/2005 8 ©IBM 2005

Lesson 2: Starting and Stopping the Applications

Introduction In this section, we will look at options when starting the Domino Server

Controller and Domino Console.

Starting the Domino Server Controller

When you start the Domino Server Controller, you run the standard Domino Server executable (nserver.exe) and append startup arguments. Since you must append the –jc argument to the nserver.exe executable, this is considered the “default” argument when starting the Domino Server Controller. There are two other optional startup arguments: -c Restricts the Domino Console from running. -s Restricts the Domino Server from running. The various startup arguments allow you to choose which applications (the Domino Console and/or Domino Server) will start and run with the Domino Server Controller. The table below summarizes startup options for the Domino Server Controller.

Command Result

c:\…\domino\nserver.exe -jc Runs the Domino Server Controller, the Domino Server (under the Controller), and the Domino Console

c:\…\domino\nserver.exe -jc -c Runs the Domino Server Controller and the Domino Server (under the Controller)

c:\…\domino\nserver.exe -jc -s

Runs the Domino Server Controller and the Domino Console

c:\…\domino\nserver.exe -jc -c -s

Runs only the Domino Server Controller

Note: When you run a Server Controller, you no longer have access to the traditional local server console. You can communicate only through the Domino Console or a console in the Domino Administrator or Web Administrator clients.


Last edited 7/21/2005 9 ©IBM 2005

Lesson 2: Starting and Stopping the Applications, Continued

Example Starting the Domino Server Controller on a Windows machine from the

Start – Run dialog box…

…will result in the Domino Server Controller loading first, followed by the Domino Console, and Domino Server. Note the arrows pointing to each of the processes started: the Domino Server Controller, Domino Console, and Domino Server.

The Domino Console GUI loads in a separate window.


Last edited 7/21/2005 10 ©IBM 2005


Activity On your machine that has Domino installed on it, start the Domino Server

Controller, Domino Console, and Domino Server by entering the following command in the Start dialog box. Substitute your program path if it is different from the screenshot.

Note that upon startup, the Domino Console automatically connects to the Domino Server Controller and the Domino Server that is running under the Controller. Leave the applications up and running for now and continue reading the following information regarding startup options.


Last edited 7/21/2005 11 ©IBM 2005


More about Startup Arguments

Why use the optional startup arguments when starting the Domino Server Controller?

-c

Example: >c:\lotus\domino\nserver.exe –jc –c

Use -c to prevent the Domino Console from running when you start the Domino Server Controller.

You might prevent the Domino Console from running on a slow machine, on a machine that is low on memory, or simply to save system resources if you will be using a remote console (like the Domino Console) to access the machine. NOTE: If you use this argument and the Domino server ID requires a password, the Domino Server starts without running its server tasks. To run the server tasks, you must connect to the server from a remote console and specify the server password when prompted.

-s

Example: >c:\lotus\domino\nserver.exe –jc –c -s Use -s to prevent the Domino Server from running when you start the Domino Server Controller. You might use the –s argument along with –c in order to run just the Domino Server Controller on a machine. In this situation, a remote administrator can connect to the Domino Server Controller with a remote console (like the Domino Server Console) via FQDN and send Controller commands that extend administrative options beyond those of traditional Domino server commands. For example, stopping and restarting the server from a remote console is not an option when you load the Domino server in the traditional way (c:\domino\nserver.exe). If you connect to a Domino server that is NOT running under the Domino Server Controller via the Web Administrator or remote console in the Domino Administrator client and quit the Domino server, there is no way to bring it back up unless you have a 3rd party application like PC Anywhere. The ability to restart the Domino Server remotely is one of the big advantages of running the Domino Server under the Domino Server Controller.


Last edited 7/21/2005 12 ©IBM 2005


Activity On your machine that is running the Domino Server Controller, Domino

Console, and Domino Server, exit the applications by clicking File – Quit Controller in the Domino Console menu bar (see below):

Click “Yes” when asked whether you are sure you want to stop the server and controller. Again on your machine that has Domino installed on it, start the Domino Server Controller, and Domino Server by entering the following command in the Start dialog box:

Note that this time upon startup, the Domino Server Controller and Domino Server start but the Domino Console does not. Leave the Controller/Server up and running and proceed reading the next page.


Last edited 7/21/2005 13 ©IBM 2005


Starting the Domino Console

You can run the Domino Console (jconsole.exe) from the program directory of a Domino server or Notes client (e.g. \Domino, \Notes). This means that you can run the Domino Console on the same machine that is already running the Domino Server Controller and/or Domino Server if you did not load the Domino Console initially (nserver.exe –jc –c), or, you can run the Domino Console on a remote machine and connect to the machine that is running the Domino Server Controller and/or Domino Server. Example:

Activity Take a moment to start the Domino Console on your client machine. Enter

the following command in the Start dialog. Substitute your program path if it is different from the screenshot.

Next, you will connect to the machine running the Domino Server Controller and Domino Server. Leave the Domino Console running on your client machine and continue reading.


Last edited 7/21/2005 14 ©IBM 2005


Connecting to the Controller

After you start the Domino Console, you need to connect to the Domino Server Controller. Clicking File – Open Server from the menu bar will bring up this dialog box:

In the Open Server dialog box, enter the following: User Name = an Administrator for your Domino Server (Security section of the Server document) Password = the user’s Internet password as defined in their Person document Server = FQDN of your machine that is running the Domino Server Controller Port = 2050 The first time you connect to the Domino Server Controller from a remote machine (you client machine, in this case), you must enter the FQDN of the machine that is functioning as the Domino Server Controller.

Activity Using the information above click File – Open in the Domino Console and

connect to the machine that is running the Domino Server Controller and Domino Server. Substitute the information from your test environment for that listed above (User Name, password, server, port). After you connect to the Domino Server Controller/Domino Server machine, leave the Domino Console running and continue reading the following pages.


Last edited 7/21/2005 15 ©IBM 2005


Domino Console as “thin” client

To run the Domino Console on a machine that does not have a Domino server, Notes client, or Domino Administrator client installed, follow these steps: On a machine that has a Domino server, Notes client or Administrator client installed, copy the following to a new directory on the desired machine: • dconsole.jar • jconsole.exe (on NT/W2K) or jconsole (on UNIX) • \jvm directory including all subdirectories (the \jvm directory is located under the \domino or \notes program directory)

Stopping the Domino Server Controller

The Domino Server Controller runs in its own window. You can minimize a the window, but do not close or kill the window to stop the Domino Server Controller if a Domino Server is running. If a Domino Server is running under the Domino Server Controller and you attempt to stop it by closing or killing the window, the Domino server tasks will not be terminated properly, and the next time you attempt to run the Domino Server under the Domino Server Controller, it will start and stop without loading. See below:


Last edited 7/21/2005 16 ©IBM 2005


Stopping the Domino Server Controller (continued)

If this happens, you must go into Task Manager and kill each process individually before you can restart the Domino Server Controller and the Domino Server running under it. Instead, use one of the following ways to shut down the Domino Server Controller (and the Domino server if it is also running): • Click File – Quit Controller from the Domino Console GUI • Issue the Controller command #Quit from the Domino Console to stop the

Domino Server Controller and the Domino Server it controls. These options will close all Domino Server processes correctly.

Stopping the Domino Console

To stop (exit) the Domino Console, do one of the following: • Click File – Exit • Enter the keyboard command Alt + Q • Kill the window (click the “X” at top right)

Last edited 7/21/2005 17 ©IBM 2005

Lesson 3: Entering Commands

Introduction Using the Domino Console, the administrator can choose from 3 different

types of commands to issue to the Domino Server Controller: • Domino Commands • Domino Controller Commands • Shell Commands

Domino Commands

Domino commands are the commands that administrators enter at the traditional Domino server console. Example: >show tasks

Controller Commands

These are commands that are specific to the Domino Controller. They can be used to control specific processes of the Domino Server or the Domino Controller itself. Many of these commands can be issue from the GUI of the Domino Console. Some Domino Controller commands are similar to Domino Commands (‘show processes’ is similar to ‘show tasks’). Use the prefix # with Domino Controller commands. Example: > #kill domino

Shell Commands

Operating system commands (‘dir’, etc). Use the prefix $ with Domino Controller shell commands. Example: >$dir c:\temp

Command modes

If you plan to enter more than one Controller command, type # and press ENTER in the Command box to change to Controller command mode. Then, you can enter Controller commands without specifying the # prefix. To exit Controller command mode, type # and press ENTER again in the Command box. The same is true for shell commands: type $ and hit ENTER in the Command box to change to Shell command mode. Type $ and hit ENTER to exit Shell command mode.


Last edited 7/21/2005 18 ©IBM 2005

Lesson 3: Entering Commands, Continued

Table of Controller Commands

Below is a table of Domino Server Controller commands. These are found in the online help for the Domino Server Console. Remember to precede each command with the # character.

Controller command Description Equivalent menu

command in the Domino Console

Broadcast message Broadcasts a specified message to all administrators connected to a Controller.

File - Broadcast

Disable username Disables a user's connection to the Controller. Connection remains disabled until you use the Enable User command or until you quit and restart the Controller. To disable more than one user's connection, separate the users' names with commas, for example:

#disable user1,user2

Edit - Controller Access

Enable username Enables a user's connection that you previously disabled using the Disable command. To enable more than one user's connection, separate the users' names with commas, for example #enable user1,user2

Edit - Controller Access

Kill Domino Stops the processes on a Domino server that is not responding

File - Kill Server

Quit Stops the Domino server and the server's Controller

File - Quit Controller

Refresh Admins Refreshes the Controller's information about administrators from the Domino Directory on the server

None

Refresh Servers Refreshes the Domino Console with the Server Controller's list of servers in the domain and also refreshes the Domino Console with the Server Controller's list of "Server only" type groups in the domain.

File - Refresh Server List


Last edited 7/21/2005 19 ©IBM 2005

Lesson 3: Entering Commands, Continued

Table of Controller Commands (continued)

Controller command Description Equivalent menu command in the Domino Console

Restart Domino Stops the processes on a Domino server that is not responding and then restarts the server

None

Set ControllerLogExpiration=days Specifies the number of days worth of log files to keep on the server. For more information, see "Controlling how long log files remain on a server" in the Domino Console online help.

None

Set ControllerLogFileName=filename Specifies the name and path of log files created on a server. For more information, see "Controlling the names and location of log files created on the server" in the Domino Console online help.

None

Set ControllerLogType=value Specifies the types of log files to create on a server or whether to disable logging on the server. For more information, see "Controlling the types of log files created on a server" in the Domino Console online help.

None

Show Users Shows the users currently connected to the Server Controller

File - Show - Users

Show Processes Shows the tasks currently running on the Domino server

File - Show - Processes

Start Domino Starts the Domino server if it is down File - Start Server

Activity Take 15 minutes to enter commands from the Domino Console on your client

machine to the Domino Server Controller and Domino Server on your server machine. Experiment with standard Domino commands, Controller commands, and shell commands. Trying issuing some of the Controller commands from the GUI in the Domino Console.

Last edited 7/21/2005 20 ©IBM 2005

Lesson 4: Using the Domino Server Controller with Partitioned Servers

Introduction In this lesson, you will learn about a common Support call involving the

Domino Server Controller on a partitioned Domino server and how to resolve it.

Scenario Port mapping is being used on a partitioned Domino server and there is an

issue with running multiple Domino Server Controllers. The first Domino Server Controller loads without any problems, but when trying to run a second instance of the Domino Server Controller on another partitioned server, he gets an error stating that port 2050 is already in use. How do we fix this?

Activity Open the Lotus Domino Support page at the following URL:

http://www-306.ibm.com/software/lotus/support/domino/support.html Take 5 minutes to search the Knowledge Base for a technote that describes this scenario When you find the technote, fill in this blank with the technote number: _______________________ Read the technote and proceed to the next activity.


Last edited 7/21/2005 21 ©IBM 2005

Lesson 4: Using the Domino Server Controller with Partitioned Servers, Continued

Activity In this activity, you will simulate the resolution to the common customer

problem described in Knowledge Base Technote #1086077 “Error Attempting to Load a Second Instance Domino Controller on a Partitioned Port-Mapped Server.” Take 10 minutes to complete the following steps in your test environment.

Step Action

1 If running, exit your Domino Server Controller and Domino Server by clicking File – Quit Controller in the Domino Console. Click OK when asked if you are sure you want to do this.

2 On your test server, locate and open the file, dcontroller.ini.

3 Locate the parameter, Port_Number =2050 and change the number to 2051. Save and close the file.

4 Start the Java Domino Controller and Domino Server with the command >nserver –jc –c

5 Open a remote session of the Domino Console. 6 Click File – Open Server 7 Enter the Administrator’s name and password for your test server. 8 Enter the name of your test server.

9 Change the default port number from 2050 to 2051, as you designated in the dcontroller.ini file in step 3.

10 Click OK and connect to your test server.

Dconsole.ini Configuration settings for the Domino Console (jconsole.exe) are stored in

the dconsole.ini file. When you change the port number in the “Open Server” dialog box (step 3), it updates the dconsole.ini file with the changed port number. See the Server= parameter for this setting.

Results While this activity did not take place on a port-mapped, partitioned Domino

server, the steps to resolve the issue as described in the technote is essentially the same. You should now be able to lead a customer to resolution of this common Support call.

Last edited 7/21/2005 22 ©IBM 2005

Lesson 5: Quick Facts and Miscellanea

Facts • You can run the Domino Console from any machine on which an R6 or

later Domino server, Notes client or Administrator client is installed. To use the Domino Console to communicate with a Domino server, the server must be running under a Server Controller.

• To run the Domino Console on a machine that does not have a Domino server, Notes client, or Administrator client installed, follow these steps:

On a machine that has a Domino server, Notes client or Administrator client installed, copy the following to a new directory on the desired machine: 1. -dconsole.jar 2. -jconsole.exe (on NT/W2K) or jconsole (on UNIX) 3. -jvm directory including all subdirectories

• When you run a Server Controller, you no longer have access to the traditional local server console. You can communicate only through the Domino Console or a console in the Domino Administrator or Web Administrator clients.

• The Server Controller listens over SSL port 2050 by default, which is adequate in most situations. However, to specify a different port, change the value of the Port_Number setting in the dcontroller.ini file located in the server's data directory.

• Configuration settings for the Domino Server Controller reside in the dcontroller.ini file. Configuration settings for the Domino Console reside in the dconsole.ini file.

• To send commands to a Server Controller, you must first log on to the server's Controller to connect to it. Once connected, you can send Domino server commands, Controller commands, and native operating system commands (shell commands). The commands you can send depends on the access you have in the Administrators section on the Security tab of the server's Server document in the Domino Directory.


Last edited 7/21/2005 23 ©IBM 2005

Lesson 5: Quick Facts and Miscellanea, Continued

On your own… There are other useful features available in the Domino Console that you

should explore on your own. See the online help in the Domino Console for detailed information regarding the following topics. • Sending a command to a group of servers • Creating, editing, or deleting a server group • Adding frequently used server groups to the Send menu • Adding frequently used commands to the Commands menu • Sending a command to a server at regular intervals • Hiding a password for a CA Process tell command • Pausing console output • Copying server output to a file • Filtering the events the console displays for a server • Showing only the events related to a specific server task • Showing only the events related to a specific process ID • Debug Output Window - Managing Java error messages

Last edited 7/21/2005 24 ©IBM 2005

Lesson 6: eSupport Resources

Online Help The online help in the Domino Console client is the best source of

information. While there is some useful information regarding the Domino Server Controller and Domino Console in the Admin Guide and the Release Notes, the online help in the Domino Console client is your best bet.

IBM Software Support: Lotus

The IBM Software Support: Lotus website is another helpful resource for issue resolution. Here, you can troubleshoot issues, plan deployments and personalize your support experience. The site can be found at: http://www-306.ibm.com/software/lotus/support/index.html

Lotus Domino Support page

For eSupport specific to Domino, navigate to this page: http://www-306.ibm.com/software/lotus/support/domino/support.html

Lotus developer resources

Developer resources for Lotus products are located here: http://www-130.ibm.com/developerworks/lotus/

Notes/Domino 6 Forum

The Notes/Domino 6 Forum on the developerWorks website is an excellent source of information regarding Domino Server Controller and Domino Console issues. http://www-10.lotus.com/ldd/nd6forum.nsf. The questions and answers that others post can be quite helpful when you are researching an issue. Also, it is common for Lotus Product Development to post answers and suggestions to queries. In general, the forum is an excellent resource for deepening your knowledge of the Domino Server Controller and Domino Console.


Last edited 7/21/2005 25 ©IBM 2005

Lesson 6: eSupport Resources, Continued

Technotes The following is a list of useful technotes from Knowledge Base regarding

the Domino Server Controller and Domino Console. Follow this URL to get to Knowledge Base: https://www-927.ibm.com/search/SupportSearchWeb/SupportSearch?pageCode=SBS&brand=lotus

Number Document Title 1086077 Error Attempting to Load a Second Instance Domino

Controller on a Partitioned Port-mapped Server 1091890 Domino 6 Console and Controller Both Show Same Process

Name in Task Manager 1092827 Using LOAD CMD from the Java Console Results in the

Console Freezing in Domino 6