Release 9.0.2
Part Number A95454-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9iAS Unified Messaging Administrator's Guide Release 9.0.2 Part Number A95454-01 |
|
This chapter contains general instructions on how to use the command-line interface. It also contains an entry for each command available in the command-line interface. Each command is followed by a brief description of its purpose. In addition, the proper syntax, keywords, and command parameters are provided.
This chapter contains the following topics:
The oesctl command enables an Oracle9iAS Unified Messaging administrator to perform some configuration and control operations on Oracle9iAS Unified Messaging services.
This command is used from within a command shell, such as /bin/csh on Unix systems, and provides a subset of the functionality available on Oracle Enterprise Manager pages for Oracle9iAS Unified Messaging. For example, oesctl can be used by an administrator to start an Oracle9iAS Unified Messaging IMAP server, but it cannot be used to modify IMAP service parameters.
Without arguments, oesctl prints out the following usage information:
% oesctl oesctl [ [<command>] [<target>|<instance>] ]
Where commands can be any of the following:
The syntax of <target> is <host>:<installation>:<service>
<host> is the host name of the computer on which server processes run
<installation> is always um_system for the this release
<service> is one of the following: gc, list, smtp_in, smtp_out, imap, pop
The syntax of <instance> is <target>:<instance_id>
The meaning of the different service names are:
<instance_id> is a number assigned to an instance when it is created. These numbers are selected automatically at instance creation time. Instance numbers cannot be configured by administrators.
All the examples that follow are executed from within a command shell running on a host named mail server.
The configuration operations either query or update the current configuration.
The query operations are:
% oesctl show targets % oesctl show processes <target> % oesctl create instance <target> % oesctl delete instance <target>
% oesctl show targets TARGET: mailserver:um_system:gc TARGET: mailserver:um_system:imap TARGET: mailserver:um_system:list TARGET: mailserver:um_system:pop TARGET: mailserver:um_system:smtp_in TARGET: mailserver:um_system:smtp_out
% oesctl show processes mailserver:um_system:imap mailserver:um_system:imap:101771055406040653 % oesctl show processes mailserver:um_system:pop No processes for mailserver:um_system:pop
In this pair of examples, there is one process instance configured for the IMAP service running on the host mail server, and there are no process instances for the POP service. A service must have at least one process instance before it can be started. From the above example we know that the POP service cannot be started on the host mail server.
% oesctl show processes mailserver:um_system:gc No processes for mailserver:um_system:gc % oesctl create instance mailserver:um_system:gc Succesfully created a new instance for a total of: 1 % oesctl show processes mailserver:um_system:gc mailserver:um_system:gc:101778964029981136
The list of process instances for the target mailserver:um_system:gc was checked just prior to instance creation, and it was empty. The create command was then used to create a new process instance for the target, after which the process instance list was checked again and found to contain the new instance.
% oesctl show processes mailserver:um_system:gc mailserver:um_system:gc:101778964029981136 % oesctl delete instance mailserver:um_system:gc Succesfully deleted an instance for a total of: 0 % oesctl show processes mailserver:um_system:gc No processes for mailserver:um_system:gc
The list of process instances for the target mail server: um_sytem: gc was checked just prior to instance deletion. The delete command was used to delete the process instance found, after which the process instance list was checked again and found to contain no more processes.
The control operations display or alter the operational state of targets and instances.
The control operations are:
% oesctl show status <target> % oesctl startup <target> % oesctl startup <instance> % oesctl shutdown <target> % oesctl shutdown <instance> % oesctl refresh <target> % oesctl refresh <instance>
Starting and Stopping a Target
% oesctl show processes mailserver:um_system:gc mailserver:um_system:gc:101779027179112257 mailserver:um_system:gc:101779029537864556 % oesctl show status mailserver:um_system:gc mailserver:um_system:gc:101779027179112257 <stopped> mailserver:um_system:gc:101779029537864556 <stopped> % oesctl startup mailserver:um_system:gc ok ok % oesctl show status mailserver:um_system:gc mailserver:um_system:gc:101779027179112257 is alive. Message from console: null mailserver:um_system:gc:101779029537864556 is alive. Message from console: null % oesctl shutdown mailserver:um_system:gc mailserver:um_system:gc:101779027179112257 Housekeeper is terminated. Message from console: null mailserver:um_system:gc:101779029537864556 Housekeeper is terminated. Message from console: null % oesctl shutdown mailserver:um_system:gc No processes configured to be running for mailserver:um_system:gc
If oesctl is used to start a target, each configured process instance is started.
% oesctl startup mailserver:um_system:gc:101779027179112257 ok % oesctl show status mailserver:um_system:gc mailserver:um_system:gc:101779027179112257 is alive. Message from console: null mailserver:um_system:gc:101779029537864556 <stopped> % oesctl shutdown mailserver:um_system:gc:101779027179112257 ok:Housekeeper is terminated. Message from console: null
In some situations administrators may want to start or stop only a particular process instances. In this case, oesctl startup <instance> and oesctl shutdown <instance> are used.
% oesctl refresh mailserver:um_system:gc:101779027179112257 ok:is refreshed. Message from console: null % oesctl refresh mailserver:um_system:gc mailserver:um_system:gc:101779027179112257 is refreshed. Message from console: null mailserver:um_system:gc:101779029537864556 is refreshed. Message from console: null
Refreshing a process instance sends the instance a message to reload its process parameters from Oracle Internet Directory.
To refresh a service target means to refresh each started process instance.
The refresh functionality can be used to change a process parameter and have the change take effect without having to stop and restart running processes. For example, the log level of the IMAP service can be changed in Oracle Internet Directory and then the service refreshed without disconnecting any users that are currently connected to the IMAP service. Executing a shutdown followed by a startup would change the logging behavior, and temporarily disconnect users.
The oesmon command enables customers to obtain raw metric data from the Oracle9iAS Unified Messaging e-mail server processes. The output of the oesmon command uses ASCII characters.
A metric is either a string or a number. Every metric is associated with an object called a managed object. Managed objects are associated with other managed objects in a parent-child relationship, forming a hierarchical tree structure of managed objects and metrics. The metrics are always leaves of the tree.
A numeric metric is either a gauge or a counter. A gauge measures the current amount of something and is characterized by a value going up and down. A counter measures an accumulated value and is characterized by the value remaining the same or becoming larger. If the value of a counter goes past the maximum supported number, the value wraps around to 0.
The integer values tracked by numeric metrics measure quantities in some unit of measure. The unit of measure for a given metric is not maintained internally and is not printed out by the oesmon command. Instead, the units are defined by the server-specific product documentation.
|
See Also:
Appendix A, "Server Statistics" for more information on server-specific statistics |
All metrics and all managed objects have names. Names contain only alphanumeric characters, including the underscore character. A name cannot contain spaces or dot characters. Names are case-sensitive. The full name of object O is formed by connecting all the names along the path from the tree root to O. In this case, O may be either a metric or a managed object.
For example:
.MTA is the full name of a managed object named MTA. It is at located immediately under the root of the tree.
.MTA.connections is the full name of a managed object named connections that is a child of the MTA object.
.MTA.connections.out.current is the full name of a numeric metric that tracks the number of currently active outbound SMTP connections.
.MTA.connections.out.total is the full name of a metric that tracks the number of outbound SMTP connections created since startup.
If you run oesmon without any arguments, it shows the command type:
Shows all possible service targets that can be polled with oesmon:
% oesmon targets TARGET: mailserver:um_system:gc TARGET: mailserver:um_system:imap TARGET: mailserver:um_system:list TARGET: mailserver:um_system:pop TARGET: mailserver:um_system:smtp_in TARGET: mailserver:um_system:smtp_out
This command queries each process instance for the metric names it currently has defined.
% oesmon names mailserver:um_system:smtp_in .DUMP.OIDStatus.Connection .DUMP.Threads.dump .ES_SPS.socket.currload .ES_SPS.socket.sockmax .ES_SPS.thread.currthreads .ES_SPS.thread.thrmax .MTA.uptime .MTA.connections.in.current .MTA.connections.in.total .MTA.msgs.deferred.current .MTA.msgs.deferred.total .MTA.receive.kbytes .MTA.receive.messages .MTA.receive.recipients .MTA.receive.time .MTA.transmit.bytes .MTA.transmit.bytes_local .MTA.transmit.messages .MTA.transmit.messages_local .MTA.transmit.recipients .MTA.transmit.recipients_local .um.admin.os_pid .um.admin.uptime
Using the command oesmon names mailserver:um_system:imap contacts each process instance that belongs to the service mailserver:um_system:imap and find out which metrics are currently defined for the process.
Many metrics are defined as soon as the process starts up, but some metrics are created dynamically during operation, and are therefore not available at all times. Therefore, the output from using the oesmon names command does not always give the same list of metric names. For example, an IMAP server process will not have any metrics available about particular user until that user logs in at least one time.
oesmon get mailserver:um_system:smtp_in.MTA.connections.in.total
This command queries each in-bound SMTP process to find out how many connections it has accepted.
% oesmon get mailserver:um_system:smtp_in .MTA.connections.in.total .MTA.connections.in.total = 352 .MTA.connections.in.total = 0
From the output it can be determined that the smpt_in service for mailserver: um_system has two process instances configured and running. The first process has received 352 connection and the second has not received any.
In the previous example, the metric given to the command was the complete name of a single metric. It is possible to retrieve values for all metrics associated with a managed object, as is shown in the following example.
This command queries in-bound SMTP processes to find out transmission metrics.
% oesmon get mailserver:um_system:smtp_in .MTA.transmit .MTA.transmit.bytes = 3282806 .MTA.transmit.bytes_local = 3282806 .MTA.transmit.messages = 330 .MTA.transmit.messages_local = 330 .MTA.transmit.recipients = 698 .MTA.transmit.recipients_local = 698 .MTA.transmit: metric not found
The name.MTA.transmit is the name of a managed object, not a metric. In this case, oesmon returns all metrics and children managed objects associated with.MTA.transmit.
From the output it can be determined that the smpt_in service for mail server: um_system has two process instances configured and running. The first process has transmitted a number of e-mail messages, and the second process has not transmitted any.
The oesmon command returns error results if a metric cannot be found or if a process instance cannot be contacted.
Example of output for undefined metric:
% oesmon get mailserver:um_system:smtp_in .nosuchmetric .nosuchmetric: metric not found
Example of output for process that does not respond:
% oesmon get mailserver:um_system:smtp_in .MTA.connections.in.total <no response>
The oesucr command creates and deletes Oracle9iAS Unified Messaging e-mail users.
OESUCR takes a file as an input. For user creation, the file should contain a list of records, separated by an empty line. Each record contains information above a user to be created. Each line in a record is a name-value pair for an attribute for the e-mail user in the directory. Each record must have at least five mandatory attributes
For user deletion, the file should contain one line that lists all the users to be deleted, separated by a comma.
This tool is only for creating and deleting e-mail users, the corresponding public users are not created or deleted by the tool. For user creation, the public users must exist before running the tool to create the corresponding e-mail users. For user deletion, after running the tool, the users are no longer valid e-mail users, but they are still users in the directory.
% oesucr <file> [-v] [-d]
<file> is the path to the file containing the user records of the users to be created or the list of users to be deleted.
The -v flag prints out debug messages.
The -d flag deletes users.
-v and -d can be used together.
The example file user_file contains the following records:
mail=testuser1@us.oracle.com mailhost=us.oracle.com orclmailquota=400000000 userpassword=welcome baseuserdn=cn=testuser1,cn=users,o=oracle,dc=com mail=testuser2@us.oracle.com mailhost=us.oracle.com orclmailquota=400000000 userpassword=welcome baseuserdn=cn=testuser2,cn=users,o=oracle,dc=com
Running the % oesucr user_file creates two e-mail users called testuser1 and testuser2. Each record in the file contains only the five mandatory attributes.
For a file user_file containing the following records:
mail=testuser1@us.oracle.com mailhost=us.oracle.com orclmailquota=400000000 userpassword=welcome baseuserdn=cn=testuser1,cn=users,o=oracle,dc=com orclMailDomainControlAci=domain mail=testuser2@us.oracle.com mailhost=us.oracle.com orclmailquota=400000000 userpassword=welcome baseuserdn=cn=testuser2,cn=users,o=oracle,dc=com
Running % oesucr user_file creates two-e-mail users called testuser1 and testuser2. The role of the first user is set to domain administrator.
The example file user_file contains the following line:
mail=testuser1@us.oracle.com,testuser2@oracle.com,testuser3@oracle.com
Running % oesucr user_file -d deletes the e-mail users: testuser1@us.oracle.com, testuser2@oracle.com, and testuser3@oracle.com.
OESDL is the command line tool for adding users to and removing users from distribution lists.
The oesdl tool takes a file as an input. The file should contain a list of records, separated by an empty line. Each record contains information to manipulate one distribution list. Each record must have the name of the list, and a list of users.
For adding users to a list, you have to indicate the type of users. You can add a regular user, a distribution list, an alias, or a foreign user to a distribution list. For description of the type of users, please refer to the distribution list documentation.
When adding users to a list, you can create the list at the same time if it does not exist. To create a new list, the owner must be specified.
% oesdl <file> [-v]
<file> is the path to [-v] the file containing the list records.
The -v flag prints out debug messages.
The example file list_file contain the following records:
listname=list1@oracle.com action=add newlist=n usertype=U users=user1@oracle.com,user2@oracle.com,user3@oracle.com listname=list2@oracle.com action=add newlist=n usertype=L users=list1@oracle.com
Running % oesdl list_file adds user1, user2, and user3 to list1@oracle.com, list1 must already exist. It then adds list1@oracle.com to another list called list2@oracle.com.
The usertype can be U for regular user, F for foreign user, L for a distribution list, and A for an alias. For description of the type of users, please refer to the distribution list documentation.
The example file list_file contains the following records:
listname=list1@oracle.com action=add newlist=y owner=user1@oracle.com usertype=U users=user1@oracle.com,user3@oracle.com
Running % oesdl list_file, creates a new list called list1@oracle.com, set its owner to user1@oracle.com, and then adds users: user1@oracle.com, and user3@oracle.com to the new list.
The example file user_file contains the following lines:
listname=list1@oracle.com action=delete usertype=U users=user1@oracle.com,user2@oracle.com listname=list2@oracle.com action=add newlist=y owner=user1@oracle.com usertype=U users=user1@oracle.com,user2@oracle.com
Running % oesdl list_file removes user1 and user2 from list1@oracle.com. It then creates a new list called list2, sets the owner user1@oracle.com, and then add user1, and user2 to the new list list2@oracle.com.
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|
