The EV Reach Command Line utility is used to perform remote administration tasks at the command line. The GovCmdLine utility has an extensive set of parameters which allow you to configure virtually every action that a EV Reach Scope Action is capable of doing. In other words, you can perform any task that EV Reach has to offer at the command prompt and in scripts.

Where can I find the utility?

This utility is called GovCmdLine.exe and is located in the installation directory of EV Reach (i.e.: C:\Program Files\EV Reach Console 9). To use it, open a command prompt and navigate to the EV Reach installation directory.

The GovCmdLine utility can be moved to another directory. However, if you do so, the following applies:

• The utility has a set of external dependencies which are: GovBase.dll, GovBaseUI.dll, GovCmn.dll, GovTalkClt.dll, GovUIExt.dll and GovCmdLine.ini. If you want the utility to have the capability to update or install the EV Reach Agents on a target machine, the following agent files must be included as well: GovAppLog.dll, GovCPL.CPL, GoverRMS.exe, GovRMHook.dll, GovSrv.exe and psapi.dll.
• Even if the GovCmdLine is a command line utility, it still requires a valid license registration like EV Reach.

Using GovCmdLine Help System

Before explaining the available command line parameters, it is better to understand the available help options so that you don't have to refer to this help guide to use GovCmdLine. GovCmdLine includes a full help system which describes the parameters, provides examples, and can even list the available attributes, methods and method arguments of each object.

To view a synopsis of all parameters, simply type GovCmdLine without any parameters. After the initial definition of the parameters, a help command section is included:

HELP COMMANDS: GovCmdLine /HELP  =>  Displays extended parameter and help definitions. GovCmdLine /HELP:Alias  =>  Displays the available attribute aliases. GovCmdLine /HELP:Show(objectLocator)  =>  Displays the available attributes for an object. GovCmdLine /HELP:ShowArg(methodLocator) =>  Displays the required arguments for a method. GovCmdLine /HELP:Examples  =>  Displays examples.

Let's define some of these help commands.

Using the /HELP:Alias parameter

The command line parameters are used to specify the object attributes to report, set, or to specify the methods to execute. The actual attribute and method names are directly derived from the Scope Action features. For example, the user object has a scope action root attribute named 'User Principal Name'. If you were to request GovCmdLine to report this attribute for the user MYDOM\MYUSER, you would type the command line:

GovCmdLine -U:MYDOM\MYUSER -R:User Principal Name

Some scope action attribute names are quite long and typing their full length name at the command prompt is tedious. For this reason, you can create attribute and method aliases. An alias is a short name for an attribute name (aliases are explained later in this article). You can view the full list of configured aliases by using the /HELP:Alias flag.

Using the /HELP:Show and /HELP:ShowArg parameters

As mentioned earlier, object properties specified in the command line are directly derived from the EV Reach Scope Action feature. Since hundreds of properties and methods are available, it would be quite hard to remember them all. The /HELP:Show( x) and /HELP:ShowArg( x) flags can be used to browse the available properties and methods at the command line.

Use the Show( x) flag to display the available properties, child objects and methods of an object. Use the ShowArg( x) flag to display the required parameters for an object method.

The only argument of the Show and ShowArg flag (that is 'x') is the full path of a parent object or method. There are three root objects in EV Reach: User, Computer, Group. These objects are always your starting point.

Typing: GovCmdLine /HELP:Show(User) displays the available properties and methods for the user object. Typing: GovCmdLine /HELP:Show(Computer) displays the available properties and methods for the computer object. Typing: GovCmdLine /HELP:Show(Group) displays the available properties and methods for the group object.

The Show flag displays information in four categories: Attribute Sets, Attributes (read only), Attributes (read/write), Methods. Each entry that is displayed can be used in a command line parameter.

To view the available properties of a child object, type the full path of the child object including its parent. For instance, the User root object has a child object called 'Logged-in Computers'. To view the properties of this type, you would type GovCmdLine /HELP:Show(user.logged-in computers). An object path may include as many child objects as needed.

Figure A 

The ShowArg flag is used to view the expected arguments of the specified method. Since a method call requires all arguments to be specified in its defined order, you will find this help flag useful. For example, the computer root object has a method called 'Set RMC Client Settings'. To view the expected arguments for this method, you would type: GovCmdLine /HELP:ShowArg(Computer.Set RMC Client Settings). The result is displayed in Figure A.

Now that you have a better idea of how to use the help system, let's look at the actual execution flags.

GovCmdLine Execution Flags

For an execution, the GovCmdLine requires at least two pieces of information: a target and an action.

Defining the target

Use the {-U:|-M:|-G:}AccountName flags to specify a target, where -U: is to target a user, -M: is to target a machine, -G: is to target a group. Then specify the name of the target after the comma.

Examples:

• GovCmdLine -U:ORION\JDoe                      ... targets the user account for John Doe on domain ORION.
• GovCmdLine -U:\\SOMEMAC\Administrator  ... targets the local user account Administrator on machine SOMEMAC.
• GovCmdLine -M:ORION\SOMEMAC              ... targets the computer SOMEMAC on domain ORION.
• GovCmdLine -M:213.125.41.13                   ... targets the computer with IP address 231.125.41.13
• GovCmdLine -G:ORION\Schema Admins      ... targets the group Schema Admins in the domain ORION.
• GovCmdLine -G:\\SOMEMAC\Administrators ... targets the local group Administrators on machine SOMEMAC.

Defining Report Actions

Use the -R:A1,A2,...,Ai flag to define reporting actions. To specify multiple attributes, separate them with a comma. The available attributes depend on the object type of the target (see Using the /HELP:Show above). An attribute can also be substituted by its alias if it has been configured.

For example, the Computer root object has an attribute set named 'Memory Information' (see Figure A). To report on the memory information of target SOMEMAC, you would type: GovCmdLine -M:SOMEMAC -R:Memory Information

The Computer object also has a child object: Shares, which has the attribute set: Share Information. To report the memory information and the shares information of target SOMEMAC, you would type: GovCmdLine -M:SOMEMAC -R:Memory Information,Shares.Share Information

Defining Set Actions

Use the -S:Atr1(val1),Atr2(val2),...,Atri(vali) flag to define set actions. To modify multiple attributes, separate them with a comma. The available write attributes depend on the object type of the target (see Using the /HELP:Show above). An attribute can also be substituted by its alias if it has been configured (see Working with Aliases below).

For example, the User root object has a writable attribute set named 'Password'. To change the password of the domain user account ORION\JDoe, you would type: GovCmdLine -U:ORION\JDoe -S:Password(userNewPassword)

To change the password of the domain user account ORION\JDoe, and set this new password as expired, you would type: GovCmdLine -U:ORION\JDoe -S:Password(userNewPassword),Password Expired(TRUE)

To change the password of the local user account JDoe on machine JDMACNAME you would type: GovCmdLine -U:\\JDMACNAME\JDoe -S:Password(userNewPassword)

Defining Execute Actions

Use the -E:M1(a1,a2,...),M2(a1,a2,...),...,Mi(a1,a2,...) flag to define execute actions. To execute multiple actions, separate them with a comma. The available methods depend on the object type of the target (see Using the /HELP:Show and /HELP:ShowArg above). A method name can also be substituted by its alias if it has been configured (see Working with Aliases below).

A method may have 0 or more arguments. For instance, the computer object includes the 'Install / Update Agents' method. This method doesn't require any arguments. Therefore, you would call it by typing: GovCmdLine -M:SOMEMAC -E:Install / Update Agents() or simply GovCmdLine -M:SOMEMAC -E:Install / Update Agents

The computer object also has a method named 'Add New Local User' which requires 8 arguments. To create a local user account you would type: GovCmdLine -M:SOMEMAC -E:Add New Local User(jdoe,John Doe,some user,jdpassword,TRUE,FALSE,TRUE,FALSE)

Defining Actions using a Definition File

The -R, -S and -E flags provide a lot of flexibility and are straight forward to use. However, configuring a command line parameter for sophisticated actions would be tedious. When you need to execute complicated actions (such as selecting WMI objects), it is best to define them in a Scope Action or Custom Action first, then use the definition flag in a parameter.

Use the -F:aDefFile flag to have the utility use a external action definition file, where 'aDefFile' is the file name or full path of either a Scope Action definition file (.gsa) or a Custom Action definition file (.gca). If you do not specify a path, the Application Data directory as defined in the Options is used.

Use the EV Reach Management Console to create either a custom action object or a scope action object with the desired actions (for a scope action, insert a dummy target object). Then execute the configured actions using the GovCmdLine utility by using the -F: flag.

For example, if you have a scope action named 'Hardware Inventory' which is configured to report all hardware information of a machine, you would type: GovCmdLine -M:SOMEMAC -F:Hardware Inventory.gsa

If you have a custom action named 'Apply Reg Hotfix2332' which is configured to import a registry file onto a machine, you would type: GovCmdLine -M:SOMEMAC -F:Apply Reg Hotfix2332.gca

Working with Aliases

The attribute and method names specified using the -R, -S and -E flags can be lengthy and tedious to write. The GovCmdLine utility allows you to configure aliases for attributes and method names which can then be used in as parameters. This is done by editing the GovCmdLine.ini file which is located under the same directory as the GovCmdLine.exe program. If the GovCmdLine.ini file doesn't exist, you can create a new one as long as you respect the format.

The GovCmdLine.ini file has two categories: OPTIONS and ALIASES. We will explain the OPTIONS category later. Here is an example of the ALIASES category:

########################################### # ALIASES CATEGORY # ALIASES: Lock = Lock Workstation ActInfo = All User Account Information mActInfo = All Computer Account Information AgentsInstall = EV Reach Agents.Install / Update Agents usrMachine = Logged-in Computers.NT Account Name,Logged-in Computers.Computer Account Information.Location

The aliases category must start with the line 'ALIASES:'. Every subsequent line is treated as an alias entry, except for comment lines which start with a '#'. An alias entry is defined with the format: ALIAS = ACTION_NAMES, where ALIAS is the short name which maps to one or more attributes as defined in ACTION_NAMES.

The ACTION_NAMES part must respect the following rules:

• You can enter any type of property: Attribute, Attribute Set, Child Object and Methods are all valid as long as the string is identical to the one you type at the command line.
• Entering multiple values for a single attribute is done with commas separating each value. Note: All attributes must be of the same type. You cannot mix Report attributes with Set or Execute attributes.
• When specifying a set or execute attribute, you can also enter the arguments. For instance, you can configure the actions: Set user password to 'welcome' and expire the password with the alias: usrResetPwd = Password(welcome),Password Expired(1)   You would then type the command line: GovCmdLine -U:DOM\USR -S:usrResetPwd . If you do not specify the arguments in the alias definition, then you must enter them at the command line.

Example

GovCmdLine -U:ORION\JDOE -R:Logged-in Computers.NT Account Name,Logged-in Computers.Computer Account Information.Location Reports a user's logged-in machine information (name and location).

If you create the alias: usrMachine = Logged-in Computers.NT Account Name,Logged-in Computers.Computer Account Information.Location, the command line then becomes: GovCmdLine -U:ORION\JDOE -R:usrMachine

Use the -O:o1=v1,o2=v2,...,oi=vi flag to set miscellaneous options as described below:

To specify the options, use the -O:optionName=value format. For instance, the command line: GovCmdLine -U:ORION\JDOE -R:usrInfo -O:AUTOINSTALL=1,OUTPUT=XML requests the EV Reach Agents to be automatically installed if needed and to report the information in XML.

You can modify the default values for each option in the GovCmdLine.ini file in the OPTION CATEGORY. Enter each option on a single line in the format: 'OPTION_NAME = OPTION_VALUE'