Chapter 17: Administering a Calendar server
Table of contents
Chapter 17
Administering a Calendar server
The Calendar client, scocal, uses a client-server architecture
to access data. When a user accesses the Calendar application to request
or update calendar data, a request is sent to a Calendar server,
which may be on the local computer or may be on a networked server computer.
The use of the client-server architecture gives you great power and
flexibility in maintaining the calendar database. For example, consider
the following system setup:
-
Four heavily used end-user computers, each with 10 users running the
Calendar.
-
One administrative computer (for example, a print spooler or database
handler) that has excess disk space and a low load average.
-
A local area network (LAN) tying each of these computers together
with SCO TCP/IP.
Given this sample setup, you would want to place the calendar data
on the administrative computer. In doing so, you see the following
benefits:
-
All 40 users have access to each other's calendars (within
the limitations of individual calendar permissions).
-
The system's load is concentrated on a computer that has excess
capacity, allowing end-users to work more efficiently.
-
The calendar data is maintained in a central location, allowing
for single-point backup and maintenance.
How the Calendar server works
-
The client queries the server for calendar data.
The client and server may be located on the same computer, or
they may be on different computers connected by SCO TCP/IP.
-
The server computer stores all of the calendar data in several database
files, which are made up of the data from each individual user's calendar.
Each time a user on a client computer uses scocal or the
scosh calendar program,
the client sends a data request to the server computer
that the server then answers.
This client-server communication is transparent to the user.
-
In a networked situation, the client and server computers must be
configured to know of each other's existence; you ensure this by using
the Calendar Configuration utility described in
``Configuring the calendar (9)''.
-
Several Calendar administration tools, described in
``Administering the calendar'',
help you maintain the calendar data on your server computer
and monitor traffic between the server and its clients.
If your client and server are located on the same machine, skip to
``Using the default configuration''.
If you are connecting to a network, choose a server computer to contain your
calendar database files and run the Calendar Configuration
utility described in
``Using the calendar over a network''.
The general procedure for network configuration is as follows:
-
Choose a computer to be your server machine. This computer should be
one that has ample free disk space and a low load average.
-
Make sure that the appropriate networking software
is installed on every computer in your local network.
-
Install SCO OpenServer on your server and client computers.
When you do so, calendar server processes start running on each computer.
-
On each computer, stop the calendar server process by running the Calendar
Configuration utility.
-
Restart the server process on the server computer. Do not restart the
server process on your clients. The system is ready for use.
-
Troubleshoot and maintain the network by using the Calendar
Administration utility described in
``Selecting the Calendar Administration utility (Cal Util)''.
Using the default configuration
If you install your SCO system without modifying any calendar
defaults, your system is ready for use in a non-networked setting.
In this case, the client and server are located on the same computer,
and client-server communication takes place via named pipes.
While the default configuration values are effective in the vast majority
of cases, you may still want to alter the retries and timeout settings
to enhance system performance.
For information on how to do this, see
``Configuring the calendar (9)''.
Using the calendar over a network
To use the Calendar application over a network, you need to run
the Calendar Configuration utility on the server
computer and each of your clients.
This utility is one of the calendar administration programs
available when you use scosh adm.
It fine-tunes many aspects of client-server communication.
The Calendar Configuration utility is described in
``Configuring the calendar (9)''.
Administering the calendar
The Calendar Administration utility allows you to perform many
useful actions on the calendar database and your users' calendars.
Use the utility by selecting Cal Util from
the scosh adm Utility list.
With this program, you can do the following:
NOTE:
When you perform maintenance on a calendar server,
you must first
pause
or
stop
the server.
Because of this, it is good practice to first inform
all Calendar users that you are going to pause
or stop the server, using a broadcast message or other means.
Selecting the Calendar Administration utility (Cal Util)
The following procedure leads you to the Calendar Administration menu:
-
Log onto your computer as root.
-
Enter scosh adm.
-
Select Utility from the main menu.
-
Select Cal Util from the Utility point-and-pick list.
The following screen appears:
Calendar Administration:
1) Get calendar statistics.
2) Archive and update calendar database.
3) Check and fix calendar database.
4) Merge two calendar databases.
5) Convert release 1.0 database to release 2.0.
6) Move a user's calendar.
7) Stop/Start calendar server.
8) Pause/Resume calendar server.
9) Configure calendar.
10) Start calendar daemon.
11) Examine calendar logfile.
Enter your choice (1-11) or enter "q" to quit:
-
Choose an option by entering the number associated with it.
After the utility called by that option runs, you return to the Calendar
Administration menu. To exit the Calendar Administration utility,
enter q.
Viewing calendar statistics / troubleshooting (1)
The calendar statistics program provides a diagnostic tool that you
can use on the server computer to determine the load being placed on
your calendar server processes.
It provides detailed information in the following areas:
-
general server information, including port number, machine name, number of
server processes started, startup dates and times, and so on
-
number of requests, retries, errors, and connections made,
including totals for the past day, totals since the server was started,
and averages per day
-
histogram showing hourly requests, retries, errors, and
connections for the current day
You can use this program to troubleshoot your system.
For example,
if the number of requests, retries, and errors at peak times are high,
you should consider additional server processes to handle these
requests.
If usage is low all day and the error rate is also low,
you may want to use a smaller number of server processes, thus cutting
down on system overhead.
For information on adding or removing server processes,
see
``Configuring the calendar (9)''.
A large number of retries can also indicate that a heavy load is
being placed on your networking software by other applications programs.
If this is the case, you may want to do some additional network
troubleshooting. Refer to your networking documentation for more information.
To view calendar statistics, follow these steps:
-
Enter 1 at the Calendar Administration menu. A screen similar
to the following appears:
Getting calendar server statistics....
Server ID: port = 3004
machine = london
servers = 6
startup date: 06-07-94
startup time: 14:10:39
time executing: 2 days 23 hours
current date: 06-07-94
current time: 20:56:37
TODAYS STATISTICS: 06:00 to 20:00
requests = 174518
retrys = 1060
errors = 0
connects = 579
AVERAGE STATISTICS PER DAY:
avg.requests = 341682
avg.retrys = 2389
avg.errors = 0
avg.connects = 1246
TOTAL STATISTICS:
total requests = 683364
total retrys = 4778
total errors = 1
total connects = 2492
TODAY'S HISTOGRAM
Time requests retrys errors connects
20:00 7750 73 0 1
19:00 4433 35 0 41
18:00 8983 72 0 7
17:00 11444 84 0 10
16:00 14183 69 0 51
15:00 15101 61 0 47
14:00 14853 95 0 42
13:00 14924 84 0 55
12:00 13818 74 0 29
11:00 14651 76 0 55
10:00 14564 67 0 65
09:00 12665 71 0 58
08:00 11125 72 0 83
07:00 8729 64 0 30
06:00 7295 63 0 5
Press <return> to continue:
-
When you are done viewing this screen, press any key and
you return to the Calendar Administration menu.
Archiving and updating the database (2)
You should periodically update your database by removing past events,
then saving these events in an archival database.
Do so by first pausing the server processes and then selecting
option 2 (Archive and update calendar database) from the
Calendar Administration screen. If you do not do this, the
calendar database may become extremely large, degrading system
performance.
The default expiration time is
30 days; that is, each time you choose this option all events
that are over 30 days old are removed from the current database
and stored in the archival database.
To archive and update the database, follow these steps:
-
Pause the server processes
by selecting option 8 from the Calendar Administration menu.
Pausing the server processes must be done before many calendar maintenance
operations and is described in
``Pausing and resuming the server (8)''.
-
Enter 2 at the Calendar Administration menu.
-
Enter a different expiration value in days if you do not want to
accept the default value of 30.
You cannot enter a value less than 7.
The data is archived in the directory
/usr/lib/sco/oadb/date, where
date is the expiration date of the events you archived. Press
<Return> to return to the Calendar Administration menu.
-
Use option 8 to resume the server processes, unless you want to perform
other tasks that require you to pause the server.
To restore an archived database, use option 4 (merge two calendar
databases) as described in
``Merging two calendar databases (4)''.
Verifying data integrity (3)
Errors in event data, permissions, or other portions of the calendar
database may develop from time to time. You can check for these errors and
fix them by choosing option 3 from the Calendar Administration menu.
-
Use the Calendar Administration menu's option 8 (described
in
``Pausing and resuming the server (8)'')
to pause the server processes.
-
Enter 3 at the Calendar Administration menu.
-
Enter the path of the database you are verifying, or press
<Return> to accept the default. Unless you have a nonstandard installation,
accept the default value.
The following messages appear:
checking event database...
checking permit database...
checking link database...
checking config database...
running calchk...
After these messages appear on the screen, any errors encountered
are repaired by the underlying utility, calchk, and you return
to the Calendar Administration menu. If you continue to encounter
errors with your database, contact your support representative.
-
Press <Return> to return to the Calendar Administration menu.
-
Use option 8 to resume the server processes, unless you want to perform
other tasks that require you to pause the server.
Merging two calendar databases (4)
You can merge databases from different machines when you create your
network, or restore an archived database by merging it with the
current database. To merge two databases, you must ensure that the
following conditions are true:
-
The server processes are not running.
To pause the server processes, use option 8.
-
The databases are the correct format. If either database was
created under SCO Portfolio version 1.0.1 or earlier, use option 5
to convert the database to the correct format.
-
Individual calendar names are not used in both databases. To
change the name of a user's calendar, use option 6 to move the
calendar out of the database, delete the calendar, and move the
calendar back in.
If you do not satisfy all of these conditions, error messages
appear when you run the merge calendar option.
To merge two calendars, follow these steps:
-
Use the Calendar Administration menu's option 8 (described in
``Pausing and resuming the server (8)'')
to pause the server processes.
-
Enter 4 at the Calendar Administration menu.
-
Enter the pathname of the database you are adding (the source database)
or enter q to quit.
-
Enter the pathname of the database you are appending to (the destination
database) or enter q to quit. The default value is
/usr/lib/sco/oadb/caldata; to accept this value, press
<Return> without entering a pathname.
After you enter the destination database pathname, the calendars
are combined and you return to the Calendar Administration menu.
Converting a calendar database (5)
If your calendar database was created under SCO Portfolio version 1.0.1 or
earlier, you must convert it to the format used by SCO OpenServer Release 5.
To do so, follow these steps:
-
Use the Calendar Administration menu's option 8 (described in
``Pausing and resuming the server (8)'')
to pause the server processes.
-
Select option 5 from the Calendar Administration menu.
-
Enter the pathname of the database you are converting (the source database)
or enter q to quit.
The default value is /usr/lib/sco/oadb/caldata;
to accept this value, press <Return> without entering a pathname.
-
Enter the pathname of the new database location (the destination
database) or enter q to quit. The default value is
/usr/lib/sco/oadb/caldata; to accept this value, press
<Return> without entering a pathname.
After your database is converted, you can access it with the Calendar
client.
Moving a user's calendar (6)
You can move a user's calendar into or out of a database. For example,
you can change the name of a user's calendar by extracting it
from the database and then moving it back under another name. You can
also move an extracted calendar file to another machine via floppy,
tape, or networking software, then move it into that machine's calendar
database.
NOTE:
It is also possible to import and export calendars
(as a normal user) using the scocalendar program. See
``Exporting and importing calendars'' in Using the Graphical Calendar
for more information.
To extract a calendar, follow these steps:
-
Use the Calendar Administration menu's option 8 (described in
``Pausing and resuming the server (8)'')
to pause the server processes.
-
Enter 6 at the Calendar Administration menu.
-
Enter the database pathname. To accept the default, which is valid
in all standard installations, press <Return>.
The Extraction/Creation menu appears.
-
Enter 1 to extract a calendar.
-
Enter the name of the calendar that you want to extract.
-
Enter the name of an output file in which to place the calendar.
The user's calendar now exists as a data file on your computer.
You cannot edit this file, but you can move or rename it if you
like.
-
Enter q to return to the Calendar Administration menu.
-
Use option 8 to resume the server processes, unless you want to perform
other tasks that require you to pause the server.
To import a calendar, follow these steps:
-
Use the Calendar Administration menu's option 8 (described in
``Pausing and resuming the server (8)'')
to pause the server processes.
-
Enter 6 at the Calendar Administration menu.
-
Enter the database pathname. To accept the default, which is valid
in all standard installations, press <Return>.
The extraction/creation menu appears.
-
Enter 2 to create a calendar.
-
Enter the name of the calendar that you want to create.
This name can be any calendar name that does not already
exist in the calendar database.
-
Enter the name of the file that contains the calendar.
The information found in the calendar data file is placed
in the calendar database under the name you chose.
-
Enter q to return to the Calendar Administration menu.
-
Use option 8 to resume the server processes, unless you want to perform
other tasks that require you to pause the server.
Stopping and starting the server (7)
You need to stop the server process on the server computer
before you can run the Calendar Configuration utility,
which is described in
``Configuring the calendar (9)''.
Stopping the server process ensures that the database is
not corrupted during configuration.
After you run this utility,
you must restart the server process so your
users can access the calendar data.
In addition, you may need to restart the server process if the
machine crashes unexpectedly.
To start or stop the server process, follow these steps:
-
Enter 7 at the Calendar Administration menu.
The Start/Stop menu appears.
-
Enter 1 to stop the server process,
2 to start the server process,
or q to quit.
-
Press <Return> to return to the Calendar Administration menu.
Pausing and resuming the server (8)
You need to pause the server process on the server computer
before you can:
-
archive and update the calendar database.
-
check and fix the data in the calendar database.
-
merge two calendar databases.
-
convert a calendar database from a previous Portfolio release to this release.
-
move a user's calendar.
Pausing the server process ensures that the calendar database is
not corrupted during your administrative activities.
After you perform one of the above tasks,
you must resume the server process so users can access calendar data.
To pause or resume the server process, follow these steps:
-
Enter 8 at the Calendar Administration menu.
The Pause/Resume menu appears.
-
Enter 1 to pause the server
process or 2 to resume the server process.
-
Press <Return> to return to the Calendar Administration menu.
Configuring the calendar (9)
Before you can use the Calendar over a network,
you must first identify which machine is to be your calendar
server and which machine or machines will be your client(s).
You must then run the Calendar Configuration utility on the server
computer and on each of the client computers.
If you are not using the Calendar over a network,
it is usually not necessary to change the default settings,
but you may want to alter the retries and timeout settings
to improve your system performance.
Use this utility to:
-
Identify which logical port is used for incoming and
outgoing calendar requests and data.
-
Specify the name of the server computer.
-
Specify how many times a client resends a given
request, assuming that no answer is received after the initial request.
-
Specify the length of time, in milliseconds, that
the client waits for a response before sending a retry.
-
Specify the total number of server processes
that the Calendar application uses to satisfy client requests.
Before you use the Calendar Configuration utility,
you must stop the server process on each computer.
The server process must not be running while you configure the calendar.
Follow these steps:
-
Enter 7 to stop the server process.
``Stopping and starting the server (7)''
describes this option.
-
Enter 9 to configure the calendar.
-
Choose the configuration option that you want to change as
described in the following table, or
enter q to quit and save changes or a to quit
without saving changes.
-
When you are done, restart the server process on the server computer
by using option 7 again. Do not restart the server process on your client
computers.
The Calendar Configuration utility consists of the following options:
- Port number (1)
-
This option indicates which logical port is used for incoming and
outgoing calendar requests and data. The port number must be greater
than 1024 and must not be used by other servers (such as a file server)
on the local network. This can be any number as long as you
use the same number on your server computer and all of its clients.
In most cases, you can use the supplied default number.
- Server name (2)
-
This option is set on client and server computers to indicate
the name of the computer that serves the calendar data.
If you are not connecting
to a network (the client and server are located on the same machine),
this option is left blank.
This option is labeled ``non-networked'' by default.
You must use this option on both the server and client computers
to specify the machine name of your server.
The name of the machine is maintained in the file /etc/systemid.
- Number of retries (3)
-
This option determines how many times a client resends a given
request, assuming that no answer was received after the initial request.
For example, if you set this number to 3, the client requests the
data up to a total of four times (the initial request plus three retries). If
the final retry is unsuccessful, the request is considered a failure.
For more information on retries, see the next option.
The default retry setting is 1.
- Timeout (4)
-
This option indicates the length of time, in milliseconds, that
the client waits for a response before sending a retry. If you set this
parameter too large, users wait longer if a retry fails. If
you set it too small, you may notice that your error rate increases as
the client does not receive a response in the allotted amount of time.
You may need to experiment with this value (using the Calendar
Statistics
command to track server usage) before you find a value with which
your system is comfortable. The default value of this option is 9000.
- Number of servers (5)
-
This option applies to the server computer only.
It specifies the total number of server processes
that the Calendar application uses to satisfy client requests.
The default value is 1, which yields two server processes (1 master,
1 slave). This is fine for a non-networked or single user
calendar system, but for larger networked installations, 4
servers is a more optimal number.
For information on adding or removing server processes,
see
``Viewing calendar statistics / troubleshooting (1)''.
- Maximum packet size (6)
-
This option is set on client and server computers to
specify the size of the data packets sent by the Calendar server.
Limit the size of the packets to be compatible with what your
network card can accept, as indicated in your network card documentation.
For example, if your network card accepts packets up to 1 KB
in size, enter 1024 for the Maximum packet size.
You must reset the packet size
if the Calendar server works properly for most calendar usage,
but you see the error message:
No response from server
when you try to open a Calendar with many events.
It is not necessary to change this value if you are not
connecting to a network.
Sample configuration
The sample configuration shown here assumes the following hardware
setup:
-
A client computer, acapulco, and a server computer, london.
-
The port number is chosen to be 3004,
the number of retries is 3,
and the timeout is 5 seconds (5000 milliseconds).
Other options remain at their default values.
Here is the Calendar Configuration utility
screen as it should appear on both machines:
Calendar client-server configuration:
1) Server port number = 3004
2) Server machine name = 'london'
3) Request retries = 3
4) Request timeout = 5000 (milliseconds)
5) Number of servers = 4
6) Maximum packet size = 4096
Select configuration to change(q=quit, a=abort):
After using the Calendar Configuration utility,
you can use the other Calendar Utility tools
described in
``Starting the calendar daemon (10)''
to administer the Calendar application.
You may also need to use the Calendar Configuration utility
at a future time to increase or
decrease the number of server processes,
or to alter other parameters. When
you do so, be sure to stop the server first.
Starting the calendar daemon (10)
The calendar daemon generates the SCO Shell event window.
Normally the calendar daemon will run all the time, but if
there is a problem with the system, such as a power failure,
it might stop running. If this happens, you must restart it
by following these steps:
-
Select option 10 from the Calendar Administration menu.
A message indicating that the calendar daemon will restart appears.
-
If no daemon was present, the program starts one.
If the daemon was already present, an error message appears explaining
that fact. In either case, press <Return>
to return to the Calendar Administration menu.
When the calendar daemon is running, it maintains a file in
/usr/lib/scosh/pipes/caldrunning.
If the daemon process is stopped using a kill -9,
this file might not be properly removed. If you try to restart
the calendar daemon and you get a message indicating that it is
already running, check to make sure this file has been removed.
Examining server log files (11)
You can determine the nature of server errors by viewing the
server logfile on the server computer. To do so, follow these steps:
-
Enter 11 at the Calendar Administration menu.
The top of the server logfile, similar to this example, appears:
Calendar server is located on machine: 'london'
DATE: 06-05-94 TIME: 01:00:59
Server exiting! Goodbye!
Press <return> to continue:
-
Press <Space> as needed to view more of the logfile.
When you reach the end of the file, press
<Return> to move back to the Calendar Administration menu.
In the example shown previously, the server could not open the
event database. This could indicate a permissions problem. While
some error messages do not pinpoint the exact nature of the problem,
most provide a basis for further troubleshooting.