8
Command-line Interface

This chapter describes the Oracle Email commands provided by the command-line interface, and includes information about the purpose of each command, as well as its syntax, keywords, and parameters.

This chapter contains the following topics:

• OESCTL
• OESUCR
• OESDL
• OESRL
• OESUTIL
• OESNG
• OESPR

OESCTL

The oesctl command provides configuration and control operations on Oracle Email services.

This command is used from a command shell, such as /bin/csh on a Unix system. It provides a subset of the functionality available on the Oracle Enterprise Manager pages for Oracle Email. For example, oesctl can be used to start an Oracle Email IMAP4 server, but it cannot be used to modify IMAP service parameters.

Getting Usage Information

Without arguments, oesctl prints out the following usage information:

% oesctl 
oesctl  [ [command] [target|instance] ] 

Where command can be any of the following:

Table 8-1 oesctl commands

Command	Description
startup	Starts individual processes associated with the target or instance
shutdown	Shuts down individual processes associated with the target or instance
create instance	Creates an instance on a target
delete instance	Deletes an instance on a target
refresh	Causes the target or instance to reload parameters from Oracle Internet Directory
show targets	Displays a list of possible targets
show status	Displays the status of the target
show processes	Displays the status of the processes associated with the target

OESCTL Syntax

The syntax of target is host:installation:service

Where:

host is the host name of the computer on which server processes run.

installation is always um_system for this release of Oracle Email.

service is one of the following:

• gc: housekeeping
• list: secure list
• smtp_in: inbound SMTP
• smtp_out: outbound SMTP
• imap: IMAP
• pop: POP

The syntax of instance is target:instance_id

Where:

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.

Examples

The following examples are executed from a command shell running on a host named mailserver.

OESCTL Configuration Operations

The configuration operations 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

Getting the List of Available Targets

% 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

Getting the List of Process Instances for a Target

In the following examples, there is one process instance configured for the IMAP service running on the host mailserver, and there are no process instances for the POP service. A service must have at least one process instance before it can be started. Since the "show targets" example shows no POP instances, the POP service cannot be started on the host mail server.

% 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

Creating a Process Instance

In the following example, the list of process instances for the target mailserver:um_system:gc is checked prior to instance creation, and found to be empty. The create command is used to create a new process instance for the target, after which the process instance list is checked again and found to contain the new instance.

% 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

Deleting a Process Instance

In the following example, the list of process instances for the target mail server: um_sytem: gc is checked prior to instance deletion. The delete command is used to delete the process instance, after which the process instance list is checked again and found to contain no processes.

% 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

OESCTL Control Operations

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

In the following example:

show shows two instances

status shows the instances are stopped

startup command starts the instances

status shows the instances running

shutdown terminates the instances

% 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 
mailserver:um_system:gc:101779027179112257 ok 
mailserver:um_system:gc:101779029537864556 ok 

% oesctl show status mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 ----Heartbeat---- 
mailserver:um_system:gc:101779029537864556 ----Heartbeat---- 

% oesctl shutdown mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 ----Shutdown----
mailserver:um_system:gc:101779029537864556 ----Shutdown----
% 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.

Starting and Stopping an Instance

To start or stop a process instance, use oesctl startup instance and oesctl shutdown instance as follows.

% oesctl startup mailserver:um_system:gc:101779027179112257 
ok 

% oesctl show status mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 ----Heartbeat---- 
mailserver:um_system:gc:101779029537864556 <stopped> 

% oesctl shutdown mailserver:um_system:gc:101779027179112257 
mailserver:um_system:gc:101779027179112257 ----Shutdown----

Refreshing Targets and Instances

% 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

The refresh instance command sends the process instance a message to reload its process parameters from Oracle Internet Directory.

The refresh instance command refreshes all started process instances of that service.

Refresh 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 IMAP service log level can be changed in Oracle Internet Directory and refreshed without disconnecting any users currently connected to the IMAP service. Conversely, executing a shutdown followed by a startup changes the logging behavior, and temporarily disconnect users.

OESUCR

The oesucr command takes input from a file of user names to perform the following tasks:

• Create and delete Oracle Email users
• Change e-mail addresses
• Specify a domain for users
• Support different character encoding types

OESUCR takes a file name as an input parameter.

For user creation, the file should contain a list of records, each followed by an empty line. Each record contains information about an e-mail user to be created. Each record in the file is a name-value pair for an attribute of the e-mail user entry in the directory. Each record must have at least three mandatory attributes:

• mail
• quota
• baseuserdn

For user deletion, the file should contain one line listing all the users to be deleted, each separated from the next by a comma.

OESUCR only creates and deletes e-mail users, not corresponding public users. For user creation, the public users must exist prior to creating 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.

Usage

% oesucr file [-v] [-d]

Where:

file is the path to the file containing the user records 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.

To change an e-mail address:

oesucr old_email_address1=new_email_address1 -change

For example:

%oesucr [e-mail]=[e-mail]
 

After this command is run, [e-mail] becomes [e-mail].

%oesucr filename -encoding=UTF-8

where filename is the name of a file to be read as UTF-8.

The file is read as UTF-8 to support a different type of character encoding.

Examples

The following examples assume the file named user_file contains the following records:

Creating Users

Running % oesucr user_file creates two e-mail users called testuser1 and testuser2. Each record in the file contains only the three mandatory attributes: the email address, the quota, and the base user DN.

mail=[e-mail] 
orclmailquota=400000000 
baseuserdn=cn=testuser1,cn=users,o=oracle,dc=com 

mail=[e-mail] 
orclmailquota=400000000 
baseuserdn=cn=testuser2,cn=users,o=oracle,dc=com

Note: : The corresponding public users must exist before running the OESUCR.

Creating Users with Optional Attributes

Running % oesucr user_file creates two-e-mail users: testuser1 and testuser2. The role of the first user is set to domain administrator.

mail=[e-mail] 
orclmailquota=400000000 
orclMailDomainControlAci=domain

mail=[e-mail]
orclmailquota=400000000
baseuserdn=cn=testuser2,cn=users,o=oracle,dc=com 

Deleting Users

Running % oesucr user_file -d deletes the e-mail users: [e-mail], [e-mail], and [e-mail].

mail=[e-mail],[e-mail],[e-mail]

Note:: The corresponding entries in the directory for these public users are not deleted by OESUCR.

Creating a User Through Command-line

The following example shows how to create a user through the command-line, without creating a new file. Only one user can be created at a time in this manner:

oesucr -cmd mail=[e-mail]
baseuserdn=cn=user1,cn=users,dc=us,dc=acme,dc=com orclmailquota=400000000 
other optional attributes

All parameters are separated by a space, and have the same names as those used in the file. All mandatory attributes must be specified, and can take any valid optional attributes.

Specifying a Real Domain for Users

The following example shows how to specify a real domain for users:

mail=[e-mail]
realdomain=acme.com
baseuserdn=......
orclmailquota=......

The e-mail address of the user becomes [e-mail], although the user's entry in Oracle Internet Directory is under acme.com. The name company1.com may or may not exist.

OESDL

OESDL is the command-line tool for adding users to and removing users from distribution lists.

The oesdl tool takes a file as input. The file should contain a list of records, each followed by an empty line. Each record must have the name of the distribution list and a list of its users.

For adding users to a distribution list, the user type must be indicated, as a regular user, a distribution list, an alias, or a foreign user, as follows:

• U: regular user
• F: foreign user
• L: distribution list
• A: alias

You can also add users to a list that does not yet exist, by creating the list in the same command that specifies its users. See section "Adding Users to a New List" for more information.

To create a new list, the owner must be specified.

Usage

% oesdl file

Where:

file is the path to the file containing the list records.

Examples

The following examples assume the file named list_file contains the following records:

Adding Users to a List

Running % oesdl list_file adds user1, user2, and user3 (usertype=U) to [e-mail] (usertype=L), which must already exist, since newlist=n (no). It also adds [e-mail] to another list called [e-mail].

listname=[e-mail] 
action=add 
newlist=n 
usertype=U 
users=[e-mail],[e-mail],[e-mail] 

listname=[e-mail] 
action=add 
newlist=n 
usertype=L 
users=[e-mail] 

Adding Users to a New List

Running % oesdl list_file creates a new list called [e-mail], sets its owner to [e-mail], and adds users [e-mail] and [e-mail] to the new list.

listname=[e-mail] 
action=add 
newlist=y 
owner=[e-mail] 
usertype=U 
users=[e-mail],[e-mail]  

Removing Users from a Distribution List

Running % oesdl list_file removes user1 and user2 from [e-mail]. It then creates a new list called list2, sets the owner as [e-mail], and adds user1, and user2 to the new list [e-mail].

listname=[e-mail] 
action=delete 
usertype=U 
users=[e-mail],[e-mail] 

listname=[e-mail] 
action=add 
newlist=y 
owner=[e-mail] 
usertype=U 
users=[e-mail],[e-mail] 

OESRL

The oesrl command creates and manages server side rules.

When creating rules, two formats of text file are accepted. The Java properties file format and the XML format.

When listing rules, only the XML format is listed.

Usage

% oesrl [-c file | -x file | -p ruleowner]

Where:

-c file: creates rules based on a Java property file

-x file: creates rules based on an XML file

-p ruleowner: prints ruleowner rules in XML

The file parameter is defined in the next section, "File Formats". Examples of using the -c parameter appear in "Creating User Rules Using Property File Input"; for the -x parameter, in "Creating User Rules Using XML File Input"; and for -p, in "Retrieving Rules".

File Formats

Property file

Property files are text files with name-value pairs. Names can be organized hierarchically and separated by periods. The following are the top-level property names used in the file:

• Ruleowner: The qualified name of the rule owner.
  • Rules owned by a user uses the user's e-mail address
  • Domain specific rules use a domain name, such as acme.com.
  • System wide rules use the system installation name stored in Oracle Internet Directory. Each property file can contain only one rule owner.
• Ruletype: Describes the rule owner types. The rule types are:
  • User
  • Domain
  • System
• Debug: If this parameter is set to TRUE, the oesrl utility prints out debugging messages. This property is optional.
• Event#: Up to six distinct events can be defined in this file; each can only appear once. The events defined should have a sequence number starting from 1, such as event1. The events are:
  • Relay
  • Reception
  • Deliver
  • Copy
  • Flag change
  • Expunge

Under each event, you can define an unlimited number of rules using property name eventname.rule#, where eventname is one of the six events and # is a sequence number starting from 1. For example, the property deliver.rule1 defines the name of the first rule under the deliver event. All attributes of this rule can be further defined under the prefix deliver.rule1.

Under each rule, one can define actions and their parameters. Rules often have conditions that need to be defined, using the following list of property names corresponding to each rule attribute:

Note: Replace the symbol # by a sequence number starting from 1.

• eventname.rule#.action#: the sequence of actions that can be defined under eventname.rule#.

  The choices of values are listed in Oracle Email Java API documentation under Java class CommandType.

• eventname.rule#.action#.param#: the parameter sequence needed for the action eventname.rule#.action#.
• eventname.rule#.active: an optional property that can be set to true or false indicating whether eventname.rule# is active.
• eventname.rule#.attr#, eventname.rule#.op#, eventname.rule#.operand#: together they represent a condition associated with the rule eventname.rule# as long the same sequence number is used.

  The choices of values for eventname.rule#.attr# are listed in Oracle Email Java API documentation under Java class AttributeType. The choices of values for eventname.rule#.op# are listed in Oracle Email Java API documentation under Java class OperatorType.

• eventname.rule#.negate#: an optional property value that can be set to true or false, indicating whether the condition number should be negated
• eventname.rule#.param#: in case when eventname.rule#.attr# requires a parameter (such as xheader), use this property to specify the parameter value.
• eventname.rule#.case#: an optional property value that can be set to true or false, indicating whether eventname.rule#.op# is case sensitive .
• eventname.rule#.cond: if multiple conditions are needed, use this property to specify whether and or or should be used to combine the conditions.

  Oracle Corporation recommends listing rule properties in order, so that readability of the property file is maximized. When running the oesrl utility, listing rule properties in order is not required.

XML

XML is the storage format of server side rules. An XML rule representation can be created directly and oesrl can be used to load the rules into the system. The XML file specified needs to a valid XML file according to the rules XML schema. To obtain the XML schema for rules, extract the schema file oracle/mail/sdk/rule/mail_rule.xsd from the Java SDK library esmail_sdk.jar under $ORACLE_HOME/jlib.

Examples

Creating User Rules Using Property File Input

This example demonstrates how to use property files to specify rules for a user, and how to use the oesrl utility to save the rules.

% cat > rules.properties
ruleowner=[e-mail]
ruletype=user
event1=deliver
deliver.rule1=Moving private messages
deliver.rule1.cond=or
deliver.rule1.attr1=rfc822to
deliver.rule1.op1=contains
deliver.rule1.operand1=[e-mail]
deliver.rule1.attr2=rfc822cc
deliver.rule1.op2=contains
deliver.rule1.operand2=[e-mail]
deliver.rule1.action1=moveto
deliver.rule1.action1.param1=/user1/Private
^D

% oesrl -c rules.properties

Creating User Rules Using XML File Input

This example demonstrates how to use XML files to specify rules for a user, and how to use the oesrl utility to save the rules.

% cat > rules.xml
<account qualifiedName=[e-mail]>
 <rulelist event=deliver>
  <rule description=Moving private messages>
   <condition junction=or>
   <condition>
    <attribute tag=rfc822to/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   <condition>
    <attribute tag=rfc822cc/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   </condition>
   <action>
    <command tag=moveto/>
    <parameter>/user1/Private</parameter>
   </action>
  </rule>
 </rulelist>
</account>
^D

% oesrl -x rules.xml

Retrieving Rules

This example demonstrates how to use list rules for a user in XML format.

% oesrl -p [e-mail]
<account qualifiedName=[e-mail]>
 <rulelist event=deliver>
  <rule description=Moving private messages>
   <condition junction=or>
   <condition>
    <attribute tag=rfc822to/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   <condition>
    <attribute tag=rfc822cc/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   </condition>
   <action>
    <command tag=moveto/>
    <parameter>/user1/Private</parameter>
   </action>
  </rule>
 </rulelist>
</account>

OESUTIL

The oesutil command-line tool enables administrators to change passwords and delete domains.

Changing Passwords

Use the following command to change passwords:

oesutil -umadmin_passwd old new -v -ocsv1

Where:

• -v is used for debugging (optional)
• -ocsv1 is used if the mail store is ocs v1 (optional)

Deleting Domains

There are five delete options that can be used:

• user: Deletes all users in a domain
• alias: Deletes all aliases in a domain
• list: Deletes all lists in a domain
• all: Deletes everything in a domain
• news: Deletes all newsgroups in a domain

Syntax

The following syntax is used for oesutil:

• -v used for debugging
• - domain=domain1 specifies the domain
• - installation=install1 specifies the installation, and is used only for in type=all cases

  oesutil -delete_domain type=user domain=edu
  oesutil -delete_domain type=list domain=com -v
  oesutil -delete_domain type=all domain=edu installation=um_system
  
  oesutil -delete_domain type=news domain=idc.oracle.com installation=um_system
  

OESNG

The OESNG command-line tool enables administrators to create and delete NNTP newsgroups in the Oracle Collaboration Suite system. This utility accepts a file as an input and creates or deletes newsgroups according to the information specified in the file.

File Format

The file passed as an input to the OESNG command-line tool must contain a list of records, each followed by an empty line. Each record consists of a set of name=value pairs containing information about the newsgroup to be created or deleted. Names are not case-sensitive. Unless indicated otherwise, all attributes can be specified only once for a group. Lines that begin with the "#" character are treated comments and are not processed by the tool.

For groups that are being deleted, it is sufficient to specify the name of the group and the action as delete.

Parameters

Table 8-2 OESNG Parameters

Parameter	Description	Acceptable Values	Default
Name	Name of the newsgroup to be created or deleted	Any valid newsgroup name	Mandatory (no default)
News Store	Name of the news store on which this newsgroup is to be created	Any valid news store in the Oracle Collaboration Suite system	Mandatory for newsgroup creation
Action	Creating or deleting the newsgroup	Create or Delete	Create
Owner	Owner of the newsgroup	Any valid e-mail address in the Oracle Collaboration Suite system	None
Description	Description for the newsgroup	Single line of text	None
Moderated Group	Boolean specifying whether the group is moderated	True or False	False
Moderator	Names the moderator for the newsgroup. Can be specified more than once for a newsgroup.	Any valid e-mail address	None
Posting Allowed	Boolean telling whether posting is allowed to the group	True or False	False
Retention Days	Number of days to retain an article in a newsgroup before being expired	Any positive integer	None
Domain	Domain the group belongs to, if the newsgroup being created or deleted is a private newsgroup	Any valid domain in the Oracle Collaboration Suite system	None
Installation	Name of the installation where the newsgroup is to be created	Any valid installation name in the Oracle Collaboration Suite system	um_system

To delete groups, specify the name of the group and the action as delete.

Usage

oesng file

where file is the path to the file containing the newsgroups to be processed.

Examples

The following examples show how to use the OESNG command-line tool.

Creating a Simple Public Newsgroup

The following example demonstrates how to create a simple public newsgroup.

oesng newsfile

where newsfile contains the following

    

name=newsgroup1
newsstore=db1.acme.com

Creating a Public Moderated Newsgroup

The following example demonstrates how to create a public moderated newsgroup that permits posting and retains articles for 15 days.

    

oesng newsfile

where newsfile contains the following:

    

name=newsgroup2
newsstore=db1.acme.com
action=create
description=A new newsgroup
moderatedgroup=true
moderator=[e-mail]
moderator=[e-mail]
postingallowed=true
retentiondays=15

Deleting a Public Newsgroup

The following example demonstrates how to delete a public newsgroup.

    

oesng newsfile

where newsfile contains the following

    

name=newsgroup5
action=delete

Creating a Public Newsgroup

The following example demonstrates how to 

• create a public newsgroup that does not allow posting,
• delete an existing private newsgroup, and
• create a private moderated newsgroup that allows posting.

  oesng newsfile
  
  

where newsfile contains the following:

    

name=newsgroup3 
newsstore=db1.acme.com 
postingallowed=false 

name=private.newsgroup1 
domain=acme.com 
action=delete 

name=private.newsgroup2 
domain=acme.com 
newsstore=db1.acme.com 
postingallowed=true 
moderatedgroup=true 
moderator=[e-mail] 
moderator=[e-mail] 

OESPR

The OESPR command-line tool enables administrators to create and delete news peers and to associate newsgroups with news peers in an Oracle Collaboration Suite system. It accepts a file as an input and creates or deletes peers according to the information specified in the file. 

File Format

The file that is passed as an input to the oespr command-line tool must contain a list of records, each followed by an empty line. Each record consists of a set of name=value pairs which contain information about the newsgroup to be created or deleted. Names are not case-sensitive. Unless indicated otherwise, all attributes can be specified only once for a peer.




Lines beginning with the "#" character are treated as comments and are not processed by the tool.

Parameters

The following describes the newsgroup parameters that can be specified in the file.

   

Table 8-3 OESPR Parameters

Parameter	Description	Acceptable Values	Default
Host Name	Fully-qualified host name of the news peer being created or deleted	Any valid peer host name	Mandatory (no default)
Port	Port on which the NNTP server is running on the peer	Any valid port	119
Action	Creating or deleting the peer	Create or Delete	Create
Accept Group	List of groups accepted from this peer; can be specified more than once for a peer.	Any valid group name. Wildcard patterns can also be specified.	None
Reject Group	List of groups to be rejected if offered by this peer; can be specified more than once for a peer.	Any valid group name. Wildcard patterns can also be specified.	None
Feed Group	List of groups for which this peer should be fed; can be specified more than once for a peer.	Any valid public newsgroup name.	None
Installation	Name of the installation where the peer is to be created.	Any valid installation name in the Oracle Collaboration Suite system.	um_system

To delete peers, specify the host name of the peer and the action as delete.

Usage

oespr file

where file is the path to the file containing the peers to be processed.

Examples

The following examples show how to use the OESPR command-line tool.

Creating a Simple Peer

The following example demonstrates how to create a simple peer.

    

oespr peerfile

where peerfile contains the following:

    

hostname=host1.acme.com

Creating a Peer Using Articles from Specific Newgroups

The following example demonstrates how to create host1.acme.com as a peer that uses articles from the comp.lang.c and comp.lang.java groups on port 2119:

    

oespr peerfile 

where peerfile contains the following: 

    

hostname=host1.acme.com 
port=2119 
feedgroup=comp.lang.c 
feedgroup=comp.lang.java 

Deleting a Peer

The following example demonstrates how to delete a peer.

    

oespr peerfile

where peerfile contains the following:

    

hostname=host1.acme.com
action=delete