Tivoli® Management FrameworkReference ManualVersion 3.7
Tivoli Management Framework Reference Manual (August 2000)
Copyright NoticeCopyright ©1998, 2000 by Tivoli Systems Inc., an IBM Company, including this documentation and all software. All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of Tivoli Systems. Tivoli Systems grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the Tivoli Systems copyright notice. No other rights under copyright are granted without prior written permission of Tivoli Systems. The document is not intended for production and is furnished “as is” without warranty of any kind. All warranties on this document are hereby disclaimed including the warranties of merchantability and fitness for a particular purpose.Note to U.S. Government Users—Documentation related to restricted rights—Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.
TrademarksThe following are trademarks or registered trademarks of Tivoli Systems or IBM Corporation: AIX, AS/400, IBM, OS/2, RS/6000, WIN-OS/2, Tivoli, TME, Tivoli Enterprise, NetView, Cross-Site, and Tivoli Ready.
In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli A/S.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group.
Java and all Java-based trademarks or logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Other company, product, and service names mentioned in this document may be trademarks or servicemarks of others.
NoticesReferences in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to Tivoli System’s or IBM’s valid intellectual property or other legally protectable right, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user.
Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York 10504-1785, U.S.A.
Tivoli Management Framework Reference Manual iii
ContentsPreface................................................................................................................. xiii
Chapter 1—CommandsEstablishing the Tivoli Environment .................................................................. 1-1
Command Syntax................................................................................................ 1-2
Object References ............................................................................................... 1-3
Registered Names ...................................................................................... 1-4
Object Paths................................................................................................ 1-4
Tivoli Transactions ............................................................................................. 1-6
Platform Commands ........................................................................................... 1-7
Administrator Commands .......................................................................... 1-7
Configuration Management Commands .................................................... 1-8
httpd Commands ........................................................................................ 1-9
Installation Commands............................................................................... 1-9
Interregion Commands............................................................................. 1-10
Kerberos Commands ................................................................................ 1-10
Endpoint and Gateway Commands .......................................................... 1-11
Low-Level Maintenance Commands ....................................................... 1-13
Managed Node Commands ...................................................................... 1-15
Notification Commands ........................................................................... 1-16
Policy Commands .................................................................................... 1-16
Query Commands..................................................................................... 1-17
Revision Control System (RCS) Commands ........................................... 1-18
RDBMS Interface Module (RIM) Commands......................................... 1-18
Scheduler Commands............................................................................... 1-19
Task Library Commands.......................................................................... 1-19
Miscellaneous Commands........................................................................ 1-20
idlarg ................................................................................................................ 1-23
idlattr ................................................................................................................ 1-25
idlcall ................................................................................................................ 1-27
iv Version 3.7
idlexception ...................................................................................................... 1-29
idlinput ............................................................................................................. 1-31
idlresult ............................................................................................................ 1-32
kadmin ............................................................................................................. 1-34
kadmind ........................................................................................................... 1-37
kdb_destroy ...................................................................................................... 1-39
kdb_edit ........................................................................................................... 1-41
kdb_init ............................................................................................................ 1-43
kdb_util ............................................................................................................ 1-45
kdestroy ............................................................................................................ 1-47
kerberos ............................................................................................................ 1-48
kinit .................................................................................................................. 1-52
klist .................................................................................................................. 1-53
kpasswd ............................................................................................................ 1-55
ksrvtgt .............................................................................................................. 1-57
kstash ............................................................................................................... 1-59
lcfd .................................................................................................................... 1-61
lcfd.sh................................................................................................................ 1-71
logls .................................................................................................................. 1-72
objcall .............................................................................................................. 1-74
odadmin ........................................................................................................... 1-77
odbls ................................................................................................................. 1-92
odstat ................................................................................................................ 1-94
oinstall ............................................................................................................ 1-101
oserv ............................................................................................................... 1-103
tivoli ............................................................................................................... 1-108
tmcmd ............................................................................................................ 1-110
tmstat .............................................................................................................. 1-112
w4inslcf.pl ..................................................................................................... 1-115
waddicon......................................................................................................... 1-118
waddpath......................................................................................................... 1-120
Tivoli Management Framework Reference Manual v
waddrealm....................................................................................................... 1-121
wadminep........................................................................................................ 1-122
wauthadmin..................................................................................................... 1-123
wbkupdb.......................................................................................................... 1-125
wbindmsg........................................................................................................ 1-129
wbroadcast ..................................................................................................... 1-131
wcatcher .......................................................................................................... 1-132
wcd ................................................................................................................. 1-134
wchkdb ........................................................................................................... 1-135
wchknode ....................................................................................................... 1-137
wchkpol .......................................................................................................... 1-139
wci .................................................................................................................. 1-141
wclient ............................................................................................................ 1-150
wclrblk ............................................................................................................ 1-156
wclrline ........................................................................................................... 1-158
wco ................................................................................................................. 1-160
wconnect ........................................................................................................ 1-168
wcpcdrom........................................................................................................ 1-173
wcpyfile........................................................................................................... 1-176
wcrtadmin ....................................................................................................... 1-177
wcrtgate........................................................................................................... 1-180
wcrtjob ............................................................................................................ 1-182
wcrtpol ............................................................................................................ 1-185
wcrtpr .............................................................................................................. 1-187
wcrtprf............................................................................................................. 1-189
wcrtprfmgr ...................................................................................................... 1-191
wcrtqlib ........................................................................................................... 1-192
wcrtquery ........................................................................................................ 1-193
wcrtrim............................................................................................................ 1-196
wcrttask ........................................................................................................... 1-199
wcrttlib ............................................................................................................ 1-202
vi Version 3.7
wdate............................................................................................................... 1-203
wdel................................................................................................................. 1-204
wdelep............................................................................................................. 1-206
wdelgate .......................................................................................................... 1-207
wdeljob .......................................................................................................... 1-208
wdelpol .......................................................................................................... 1-209
wdelpr ............................................................................................................ 1-210
wdelrealm ....................................................................................................... 1-211
wdelsched ...................................................................................................... 1-212
wdeltask ......................................................................................................... 1-213
wdepot............................................................................................................. 1-214
wdisconn ........................................................................................................ 1-217
wdiskspace ..................................................................................................... 1-219
wdistrib .......................................................................................................... 1-220
wdisttask ......................................................................................................... 1-222
wdskspc........................................................................................................... 1-224
weditini ........................................................................................................... 1-226
wedsched ........................................................................................................ 1-228
wenblsched .................................................................................................... 1-234
wep ................................................................................................................. 1-236
wepmgr ........................................................................................................... 1-243
wexpnotif ....................................................................................................... 1-245
wgateway ........................................................................................................ 1-246
wgetadmin ...................................................................................................... 1-250
wgetallinst ...................................................................................................... 1-252
wgetdfpol ....................................................................................................... 1-253
wgeteppol........................................................................................................ 1-255
wgetjob .......................................................................................................... 1-257
wgetkey........................................................................................................... 1-258
wgetpolm ....................................................................................................... 1-260
wgetpr ............................................................................................................ 1-262
Tivoli Management Framework Reference Manual vii
wgetprf ........................................................................................................... 1-263
wgetquery........................................................................................................ 1-265
wgetrim ........................................................................................................... 1-267
wgetsched ....................................................................................................... 1-268
wgetsub .......................................................................................................... 1-271
wgettask ......................................................................................................... 1-272
wgetval ........................................................................................................... 1-274
whostid ........................................................................................................... 1-276
wiconv............................................................................................................. 1-277
wident ............................................................................................................. 1-278
widmap............................................................................................................ 1-279
wifconfig ........................................................................................................ 1-282
winsblk ............................................................................................................ 1-284
winsline .......................................................................................................... 1-286
winstall ........................................................................................................... 1-288
winstdir .......................................................................................................... 1-291
winstendpt ...................................................................................................... 1-292
winstlcf............................................................................................................ 1-293
winstruct.......................................................................................................... 1-299
winstruct_plus ................................................................................................. 1-302
winstruct_task ............................................................................................... 1-305
winterp ........................................................................................................... 1-307
wlcftap ............................................................................................................ 1-308
wln .................................................................................................................. 1-310
wlocalhost ...................................................................................................... 1-312
wlocktmr ........................................................................................................ 1-313
wlocpath .......................................................................................................... 1-315
wlookup .......................................................................................................... 1-317
wls .................................................................................................................. 1-319
wlsconn .......................................................................................................... 1-321
wlsendpts......................................................................................................... 1-323
viii Version 3.7
wlsinst ............................................................................................................. 1-324
wlsnotif .......................................................................................................... 1-327
wlspol ............................................................................................................. 1-330
wlspolm .......................................................................................................... 1-331
wlsrealms ........................................................................................................ 1-333
wlssub ............................................................................................................ 1-334
wlstlib ............................................................................................................ 1-336
wmailhost ....................................................................................................... 1-337
wmannode ...................................................................................................... 1-338
wmdist............................................................................................................. 1-339
wmdistgui ....................................................................................................... 1-350
wmemsize ...................................................................................................... 1-351
wmerge .......................................................................................................... 1-352
wmrgaef .......................................................................................................... 1-354
wmrgini .......................................................................................................... 1-356
wmv ............................................................................................................... 1-357
wpatch ............................................................................................................ 1-359
wping ............................................................................................................. 1-361
wpopulate ....................................................................................................... 1-362
wputeppol ....................................................................................................... 1-364
wputpolm ....................................................................................................... 1-365
wpwd .............................................................................................................. 1-369
wrcs ................................................................................................................ 1-370
wrcsdiff .......................................................................................................... 1-377
wrcsmerge ...................................................................................................... 1-379
wrefresh ......................................................................................................... 1-381
wregister ........................................................................................................ 1-382
wrestart .......................................................................................................... 1-384
wrimtest .......................................................................................................... 1-385
wrimtrace ........................................................................................................ 1-387
wrlog .............................................................................................................. 1-389
Tivoli Management Framework Reference Manual ix
wrm ................................................................................................................ 1-393
wrmnode ........................................................................................................ 1-395
wrplblk ............................................................................................................ 1-397
wrplline ........................................................................................................... 1-399
wrpt ................................................................................................................ 1-401
wrunas ............................................................................................................. 1-409
wruninvquery .................................................................................................. 1-410
wrunjob .......................................................................................................... 1-414
wrunquery ....................................................................................................... 1-417
wruntask ......................................................................................................... 1-419
wschedjob ...................................................................................................... 1-424
wserver ........................................................................................................... 1-429
wsetadmin ...................................................................................................... 1-437
wsetdfpol ........................................................................................................ 1-439
wseterr............................................................................................................. 1-440
wsetjob ........................................................................................................... 1-441
wsetlang...................................................................................................... 1-444
wsetpkey ......................................................................................................... 1-446
wsetpm ........................................................................................................... 1-447
wsetpr .............................................................................................................. 1-448
wsetquery ........................................................................................................ 1-450
wsetrim............................................................................................................ 1-452
wsetrimpw....................................................................................................... 1-454
wsettap ........................................................................................................... 1-455
wsettask .......................................................................................................... 1-457
wsetval ............................................................................................................ 1-459
wsndnotif ........................................................................................................ 1-461
wstarthttpd....................................................................................................... 1-463
wstartsched ..................................................................................................... 1-464
wstophttpd....................................................................................................... 1-465
wsub ............................................................................................................... 1-466
x Version 3.7
wsupport ........................................................................................................ 1-468
wtailnotif ........................................................................................................ 1-471
wtaskabort ...................................................................................................... 1-473
wtimezone ...................................................................................................... 1-475
wtemp ............................................................................................................. 1-476
wtll .................................................................................................................. 1-478
wtmrname ....................................................................................................... 1-482
wtrace ............................................................................................................. 1-483
wuname .......................................................................................................... 1-488
wuninst............................................................................................................ 1-489
wunstmn.......................................................................................................... 1-492
wunsub ........................................................................................................... 1-495
wupdate .......................................................................................................... 1-497
wvalidate ........................................................................................................ 1-499
wxterm ........................................................................................................... 1-500
Chapter 2—Tivoli-Defined PolicyProfile Manager Policy ....................................................................................... 2-1
Default Policy Methods ............................................................................. 2-2
Validation Policy Methods......................................................................... 2-2
Task Library Policy ............................................................................................ 2-3
Default Policy Methods ............................................................................. 2-3
Validation Policy Methods......................................................................... 2-4
Editing Profile Manager and Task Library Policy.............................................. 2-4
Endpoint Policy .................................................................................................. 2-6
allow_install_policy .................................................................................. 2-7
after_install_policy................................................................................... 2-10
login_policy ............................................................................................. 2-13
select_gateway_policy ............................................................................. 2-15
Editing Endpoint Policy ........................................................................... 2-19
Profile Manager and Task Library Policy Methods ......................................... 2-20
pm_def_profile_managers ................................................................................ 2-21
Tivoli Management Framework Reference Manual xi
pm_def_subscribers ......................................................................................... 2-22
pm_val_remove_subscribers............................................................................. 2-24
pm_val_remove_subscription ........................................................................... 2-26
pm_val_subscribers........................................................................................... 2-28
pm_val_subscription ......................................................................................... 2-29
tl_def_dist_mode .............................................................................................. 2-30
tl_def_man_nodes ............................................................................................ 2-31
tl_def_prof_mgrs .............................................................................................. 2-32
tl_val_man_nodes ............................................................................................ 2-33
tl_val_prof_mgrs .............................................................................................. 2-34
tl_val_set_gid ................................................................................................... 2-35
tl_val_set_uid ................................................................................................... 2-36
xii Version 3.7
Preface
Tivoli Management Framework Reference Manual xiii
PrefaceTivoli® Management Framework is the base component for the Tivoli product line. Using Tivoli Management Framework and a combination of Tivoli applications, you can manage large distributed networks with multiple operating systems, various network services, diverse system tasks, and constantly changing nodes and users.
Tivoli Management Framework provides a set of common services or features that are used by the Tivoli applications installed on Tivoli Management Framework. The services provided by Tivoli Management Framework include, but are not limited to, the following:
■ A Dynamic Host Configuration Protocol (DHCP) service that enables dynamic IP addressing for installations that use DHCP
■ A task library through which you can create tasks and execute the tasks on multiple Tivoli resources
■ A scheduler that enables you to schedule all Tivoli operations, including the execution of tasks created in the Tivoli task library
■ An RDBMS Interface Module (RIM) that enables some Tivoli applications to write application-specific information to relational databases
■ A query facility that enables you to search and retrieve information from a relational database
Tivoli applications installed on Tivoli Management Framework are enabled to use the services provided by Tivoli Management Framework.
This manual provides instructions for performing tasks from the Tivoli command line interface (CLI).
Preface
xiv Version 3.7
Who Should Read This ManualThis manual is intended for use by system administrators who use the command line to perform Tivoli operations. It is also helpful in writing scripts that are later run as Tivoli tasks. Users of this manual should have some knowledge of the following:
■ The UNIX® or Microsoft® Windows NT® operating systems
■ Shell programming
■ The Motif or Windows® environment
What This Manual ContainsThe Tivoli Management Framework Reference Manual contains the following sections:
■ Chapter 1, “Commands”
Discusses Tivoli CLI commands
■ Chapter 2, “Tivoli-Defined Policy”
Discusses the default and validation policies for Tivoli Management Framework components
Conventions Used in This ManualThe manual uses several typeface conventions for special terms and actions. These conventions have the following meaning:
Bold Commands, keywords, file names, authorization roles, URLs, or other information that you must use literally appear in bold. Names of buttons and other controls also appear in bold.
Italics Variables and values that you must provide appear in italics. New terms appear in italics when they are defined in the text. Words and phrases that are emphasized also appear in italics.
Monospace Code examples, output, and system messages appear like this, in a monospace font.
Preface
Tivoli Management Framework Reference Manual xv
Accessing Publications OnlineThe Tivoli Customer Support Web site (http://www.tivoli.com/support/) offers a guide to support services (the Customer Support Handbook); frequently asked questions (FAQs); and technical information, including release notes, user’s guides, redbooks, and white papers. You can access Tivoli publications online at http://www.tivoli.com/support/documents/. The documentation for some products is available in PDF and HTML formats. Translated documents are also available for some products.
To access most of the documentation, you need an ID and a password. To obtain an ID for use on the support Web site, go to http://www.tivoli.com/support/getting/.
Resellers should refer to http://www.tivoli.com/support/smb/index.html for more information about obtaining Tivoli technical documentation and support.
Business Partners should refer to “Ordering Publications,” on page -xv for more information about obtaining Tivoli technical documentation.
Ordering PublicationsOrder Tivoli publications online at http://www.tivoli.com/support/Prodman/html/pub_order.html or by calling one of the following telephone numbers:
■ U.S. customers: (800) 879-2755
■ Canadian customers: (800) 426-4968
Providing Feedback about PublicationsWe are very interested in hearing about your experience with Tivoli products and documentation, and we welcome your suggestions for improvements. If you have comments or suggestions about our products and documentation, contact us in one of the following ways:
■ Send e-mail to [email protected].
■ Fill out our customer feedback survey at http://www.tivoli.com/support/survey/.
Preface
xvi Version 3.7
Contacting Customer SupportIf you need support for this or any Tivoli product, contact Tivoli Customer Support in one of the following ways:
■ Submit a problem management record (PMR) electronically from our Web site at http://www.tivoli.com/support/reporting/. For information about obtaining support through the Tivoli Customer Support Web site, go to http://www.tivoli.com/support/getting/.
■ Submit a PMR electronically through the IBMLink™ system. For information about IBMLink registration and access, refer to the IBM Web page at http://www.ibmlink.ibm.com.
■ Send e-mail to [email protected].
■ Customers in the U.S. can call 1-800-TIVOLI8 (1-800-848-6548).
■ Customers outside the U.S. should refer to the Tivoli Customer Support Web site at http://www.tivoli.com/support/locations.html for customer support telephone numbers.
When you contact Tivoli Customer Support, be prepared to provide the customer number for your company so that support personnel can assist you more readily.
Tivoli Management Framework Reference Manual 1–1
Com
mands1
1Commands
Tivoli commands enable you to perform system operations from a UNIX command line instead of using the Tivoli desktop. This is often useful when you do not have access to a graphical display such as when logging in over a modem line.
All Tivoli end-user commands begin with a ‘w’ to identify them as Tivoli commands. Commands are also developed with a w+verb+object syntax, which matches the way you would think of the action. For example, if you want to create a task, use the wcrttask command. To delete a job, use the wdeljob command.
It is often convenient or more appropriate to invoke a Tivoli management application operation from the command line than from the graphical user interface. For example:
■ You may not have access to a graphical user interface, perhaps because you dialed in over a modem
■ A number of operations are going to be grouped together inside a shell script
■ You would rather invoke a command from a shell
Establishing the Tivoli EnvironmentWhen Tivoli Management Framework was installed, two setup files were created that allow you to easily establish the correct search paths and environment variables. These files are available on any client or the server in the Tivoli Management Region (TMR).
1–2 Version 3.7
To set up the UNIX system environment to run Tivoli commands, perform the following steps:
1. Log in to a Tivoli client or the TMR server on which your Tivoli administrator has an alias with the super role for the TMR. See the Tivoli Management Framework User’s Guide for details about creating Tivoli administrators with authorization roles for the TMR.
2. Run one of two environment initialization and setup scripts, depending on your UNIX shell.
If you are using the Bourne shell, run the following command:
. /etc/Tivoli/setup_env.sh
If you are using the C shell, run the following command:
source /etc/Tivoli/setup_env.csh
To set up the Windows NT system environment for Tivoli commands, run the following commands from a Windows NT command prompt:%SystemRoot%\system32\drivers\etc\Tivoli\setup_env
sh
. $SystemRoot/system32/drivers/etc/Tivoli/setup_env.sh
Note: Some Windows NT commands are scripts and must be run with sh.
You now have an environment ready to perform Tivoli operations.
Command SyntaxThe commands in this book use the following special characters to define the command syntax:
[ ] Identifies optional arguments. Arguments not enclosed in brackets are required.
… Indicates that you can specify multiple values for the previous argument.
| Indicates mutually exclusive information. You can use the argument to the left of the separator or the argument to the right of the separator. You cannot use both arguments in a single use of the command.
Tivoli Management Framework Reference Manual 1–3
Com
mands
{ } Delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are optional, they are enclosed in brackets ([ ]).
\ Indicates that the command line wraps to the next line. It is a continuation character.
For example:
logls [–Dofls] [–k dir] [–m maxdlen] logname …
logname is the only required argument for the logls command. The ellipsis marks (…) following the logname option indicate that you can specify multiple log file names. The brackets around the other arguments indicate that these arguments are optional.
Another example is the wchkdb command:
wchkdb [–o outfile] [–u] [–x] {–f infile | –i | object…}
In this example, the –f infile, –i, and object arguments are mutually exclusive. The braces ({}) indicate that one of these arguments is required. If you choose to specify the object option, you can optionally specify more than one object name or ID.
Note: The commands in this chapter assume Bourne shell. From a Windows NT command prompt, adjust the command syntax as necessary or to access a Tivoli-ported version of the Bourne shell, enter the command sh before entering other commands in this chapter.
The arguments for each command are listed in alphabetical order in the Arguments section, unless the arguments must be used in a specific order to implement the command.
Object ReferencesWhen an object is referenced in a command issued from the command line, the reference is not an absolute object reference like those used in programming. Instead, a user-friendly name is used. This user-friendly name derives from a name given to the object by the user of the application, such as when a policy region is created.
Two different forms of names can be used with commands:
■ Registered names
1–4 Version 3.7
■ Object paths
Tivoli programs that use a command line interface (CLI) support both naming schemes. Sometimes, you will find it more convenient to use one form over the other. If you receive an error message indicating that a resource cannot be found, try a different naming convention.
Registered Names The key concept behind the name registry is a registered name. A registered name is the name by which a resource instance is registered with the name registry when it is created. Every resource has a name and is of some particular type. For example, a printer called “lp01” has a name lp01 and is of type printer. Some examples of registered names used as arguments for the wls command are as follows:wls @PolicyRegion:Serverswmv @ManagedNode:ayers-rock @PolicyRegion:Servers
The syntax for specifying a resource using the registered name facility is @type:name, where type is the resource type and name is the particular instance of that resource on which you want to perform some operation.
The name registry does not allow two resources of the same type to have the same name within a single TMR. However, it is possible for resource names to be duplicated within two or more connected TMRs. If you attempt to perform an action on a resource with a duplicated name, an error message is returned, and the action is not performed. To avoid this situation, you should either rename one of the resources or differentiate between the resources by appending a region name to the resource name, as follows:wls @ManagedNode:moria#moria-Region
Object PathsObject paths are similar to path names in file systems and may be relative or absolute. An absolute path is one that starts with a slash (/) character. A relative path can start with any character including the special path components period (.) and double period (..). Some examples of object path names used as arguments for the wls command are as follows:
Tivoli Management Framework Reference Manual 1–5
Com
mands
wls /Regions/Serverswmv ../Servers/ayers-rock /Regions/Servers
The syntax for specifying a resource using the object path name style is /distinguished/parent/[type:]name, where distinguished is a resource type, parent is the start of the object path name, type is used to further identify a resource, and name is the particular instance on which you want to perform some operation. You often use the optional type qualifier when you need to name a particular resource that has the same name as some other resource of a different type.
For example, suppose policy region Engineering had a profile manager called Servers and a policy subregion called Servers. To specify the profile manager using an object path name, you could use the following:wls /Regions/Engineering/ProfileManager:Servers
If you specify a resource using an absolute path, its location is not ambiguous between connected TMRs. However, if you use a relative path, both your home and current administrator collection must be located before the resource can be found. Each administrator’s home collection is /Administrators/Name, where Name is the administrator’s Tivoli name.
If you have recently issued a wcd command, Tivoli contains a record that specifies the location of the current administrator collection. Otherwise, no such record exists, and in this case, the current administrator collection can be ambiguous if multiple TMRs are connected. For example, suppose you are an administrator named John (with a login name johnc) in TMR A, and there is another administrator named John (with a login name of jsmith) in TMR B. When you specify an action to be performed on a resource, Tivoli searches for the /Administrators/John collection. The search finds collections belonging to you and jsmith. Because Tivoli cannot determine which home collection you meant to specify, an error message is returned, and the action is not performed. You can execute the wcd command to prevent this problem from occurring.
1–6 Version 3.7
Tivoli TransactionsBecause Tivoli products run in a distributed environment, program error conditions can cause consistency errors between the Tivoli object database and the actual work environment. For example, consider Tivoli User Administration, which creates a new user on a managed node. Tivoli User Administration must create a new user object and add an entry to the node’s password file. If an error occurs while writing the file, Tivoli User Administration must have a way to remove the user object. Otherwise, the Tivoli database is left in an inconsistent state.
To solve this problem, Tivoli provides a transaction system. A transaction is a set of operations that must all complete successfully. If any operations in a transaction fail, all changes made by the other operations are aborted.
The Tivoli transaction allows you to create nested transactions, which form transaction hierarchies. A method can be invoked in one of four ways:
■ The method is not part of a transaction.
■ The method is the top of a transaction hierarchy.
■ The method is a subtransaction of a top-level transaction.
■ The method is a revocable subtransaction.
A top-level transaction only succeeds if its subtransactions succeed. If the top-level transaction fails, Tivoli undoes all changes made by the transaction and its subtransactions. Subtransactions can themselves have subtransactions on which they depend.
When a subtransaction is revocable, it can abort without forcing the parent transaction to abort. The parent can decide whether the failure is severe enough to warrant aborting the entire transaction. For example, consider a transaction that calls a revocable subtransaction to write a set of database records. If the subtransaction fails after writing 99 percent of the records, the parent may choose to succeed anyway. However, if the method fails after writing only five percent, the parent may choose to fail and undo the records that have been written.
Tivoli Management Framework Reference Manual 1–7
Com
mands
The Tivoli task library runs jobs using this transaction model. Tasks run from the Tivoli desktop are executed as top-level transactions. You can, however, create a task that runs a shell script, which in turn runs other Tivoli tasks as either subtransactions or as revocable subtransactions.
Platform CommandsThe following sections list the Tivoli Management Framework commands by component. Each section contains a table of command names and purpose statements.
Administrator Commands
Command Purpose
wauthadmin Adds, removes, or displays the root authority of Tivoli administrators in a TMR
wcrtadmin Creates a new Tivoli administrator
wgetadmin Lists information about a Tivoli administrator
widmap Lists and modifies user login mapping
wsetadmin Changes information about a Tivoli administrator
wsetlang Determines the operating system locale to use for a TMR server or managed node
1–8 Version 3.7
Configuration Management Commands
Command Purpose
wcrtprf Creates a new profile or clones an existing profile
wcrtprfmgr Creates a profile manager
wdistrib Distributes one or more profile copies
wgetprf Retrieves subscription copies of one or more profiles
wgetsub Lists the subscribes of a profile manager
wlssub Lists the profile managers to which a host, NIS domain, or profile manager subscribes
wpopulate Populates a profile from system files
wsetpm Enables or disables a profile manager to operate in dataless mode
wsub Subscribes Tivoli resources to a profile manager
wuninst Uninstalls Tivoli applications from a specified node or from the entire TMR
wunsub Removes Tivoli resources from a profile manager’s subscription list
wvalidate Validates a profile against its validation policy
Tivoli Management Framework Reference Manual 1–9
Com
mands
httpd Commands
Installation Commands
Command Purpose
waddrealm Registers an HTTP 1.0 authentication realm with the HTTP daemon.
wdelrealm Deletes a registered HTTP 1.0 authentication realm. The HTTP daemon must be restarted before the realm is actually deleted.
wlsrealms Lists the currently registered HTTP 1.0 authentication realms.
wstarthttpd Starts the Tivoli HTTP daemon.
wstophttpd Stops the Tivoli HTTP daemon.
Command Purpose
oinstall Installs, updates, or removes the Tivoli object dispatcher service in the Windows NT Service Manager (Windows NT only)
wclient Installs Tivoli clients
wcpcdrom Copies installation images from a CD to a system directory
winstlcf Installs an endpoint on a UNIX or Windows NT workstation
wmailhost Specifies the mail server used by Tivoli on Windows NT
wpatch Installs a Tivoli patch
1–10 Version 3.7
Interregion Commands
Kerberos Commands
wserver Installs the TMR server
wsettap Sets the properties of the Tivoli Authentication Package (Windows NT only)
Command Purpose
Command Purpose
wconnect Connects two Tivoli management regions
wdisconn Disconnects two Tivoli management regions
wlookup Searches for a resource’s object reference
wlsconn Lists the current TMR connections or information about a single connection
wregister Registers a resource with the name registry
wtmrname Displays or changes the name of the local TMR
wupdate Updates resources in the local name registry
Command Purpose
kadmin Network utility for Kerberos database administration
kadmind Network daemon for Kerberos database administration
kdb_destroy Destroys a Kerberos key distribution center database
Tivoli Management Framework Reference Manual 1–11
Com
mands
Endpoint and Gateway Commands
kdb_edit Kerberos key distribution center database editing utility
kdb_init Initializes a Kerberos key distribution center database
kdb_util Kerberos key distribution center database utility
kdestroy Destroys Kerberos tickets
kerberos Introduction to the Kerberos authentication service
kinit Kerberos login utility
klist Lists currently held Kerberos tickets
kpasswd Changes a user’s Kerberos password
ksrvtgt Fetches and stores Kerberos ticket-granting-ticket using a service key
kstash Stashes the Kerberos key distribution center database master key
Command Purpose
Command Purpose
lcfd Starts the endpoint daemon (lcfd) on a PC endpoint, installs or removes the daemon as a service on Windows NT
lcfd.sh Starts or stops the endpoint daemon (lcfd) on UNIX endpoints
w4inslcf.pl Installs an endpoint on an AS/400 system
waddpath Adds an entry to the path statement in the registry hive of the current control set (Windows NT only)
1–12 Version 3.7
wadminep Performs automatic upgrade of an endpoint client
wclrblk Removes a block of statements from a file
wclrline Removes a single line from a file
wcpyfile Enables an .NCF configuration program to copy a file (NetWare only)
wcrtgate Creates an endpoint gateway
wdelep Deletes an endpoint
wdelgate Deletes an endpoint gateway
wdskspc Verifies the amount of disk space available (DOS, Windows 95, Windows 98, Windows NT, and NetWare only)
weditini Modifies the groups, variables, and values in an .INI file
wep Performs actions on endpoint information contained in the endpoint list
wepmgr Provides control and configuration for the endpoint manager
wgateway Starts, stops, or lists the properties of an endpoint gateway
wgetkey Retrieves the subkey listing in a registry hive (Windows 95, Windows 98, and Windows NT)
wgetval Retrieves a registry subkey (Windows 95, Windows 98, and Windows NT only)
winsblk Inserts a block of statements into a file
winsline Inserts a single line into a file
Command Purpose
Tivoli Management Framework Reference Manual 1–13
Com
mands
Low-Level Maintenance Commands
winstlcf Installs an endpoint on UNIX and Windows NT workstations
wlsendpts Lists all the endpoints subscribed to a profile manager
wmrgini Merges groups and variables from one .INI file into another
wrestart Initiates a system restart and optional reboot (Windows 95, Windows 98, and Windows NT only)
wrplblk Replaces a block of statements in a file
wrplline Replaces a single line in a file
wseterr Sets the return code from a batch file for a configuration program
wsetval Sets a registry key value (Windows 95, Windows 98, and Windows NT only)
Command Purpose
Command Purpose
idlarg Extracts individual arguments from an argument list returned by the idlinput command
idlattr Gets or sets implementation attributes
idlcall Provides a method of invoking Interface Definition Language (IDL) operations from the shell command line
idlexception Raises exceptions for a shell method
1–14 Version 3.7
idlinput Gets the input or inout arguments list to a shell method
idlresult Formats inout or output arguments, or the result (if any) of a shell method
logls Creates a readable version of a transaction log file
objcall Performs an object call from the shell
odadmin Manages object dispatchers
odbls Lists the contents of an object database
odstat Lists the status of current and recent object calls
oserv Provides operations to control and configure object dispatchers
tmcmd Forces a change of state of a running transaction
tmstat Displays the status of current transactions and locks
wlocalhost Sets the name of the local host in the Windows NT registry (Windows NT only)
wlocktmr Places the current TMR in maintenance mode
wmailhost Specifies the mail server used by Tivoli on Windows NT
Command Purpose
Tivoli Management Framework Reference Manual 1–15
Com
mands
Managed Node Commands
Command Purpose
wclient Creates a managed node
wdate Prints out the current date and time of the managed node
wdiskspace Prints the number of free kilobytes available in the specified directory (file system) of the specified managed node
whostid Prints the host ID of the specified managed node
wifconfig Queries or changes the IP interfaces on a managed node
winstdir Prints out the path of the installation directory of the specified managed node
winterp Prints the interpreter type of the specified managed node
wmannode Returns the properties of a managed node
wmemsize Reports the amount of physical memory of a managed node
wtimezone Prints the value of the specified system’s time zone
wuname Lists operating system information
wunstmn Removes Tivoli Management Framework files from a managed node
wxterm Starts an Xterminal session on a UNIX managed node
1–16 Version 3.7
Notification Commands
Policy Commands
Command Purpose
wbroadcast Broadcasts a message to all Tivoli desktops
wexpnotif Expires notices from a notice group
wlsnotif Lists notices on an administrator’s bulletin board
wsndnotif Translates standard input into a message structure and sends it to the notification server
wtailnotif Connects to the notification server and displays new notices as they are posted
Command Purpose
wchkpol Checks policy region members against policy
wcrtpol Creates a new policy object for a class
wcrtpr Creates a policy region
wdelpol Deletes a default policy object
wdelpr Deletes a policy region
wgetdfpol Lists a default policy object
wgeteppol Lists the body and constant values of an endpoint policy script
wgetpolm Lists the body or constant value of a default or validation policy method
Tivoli Management Framework Reference Manual 1–17
Com
mands
Query Commands
wgetpr Lists the properties of a policy region
wlspol Lists available policy default and validation objects for a Tivoli resource
wlspolm Lists policy methods for a Tivoli resource
wputeppol Replaces an endpoint policy script that has been modified
wputpolm Replaces a policy method’s body
wsetdfpol Sets the default policy for a class
wsetpr Assigns the policy used in a policy region, enables or disables policy validation, and adds or removes a managed resource in a policy region
Command Purpose
Command Purpose
wcrtqlib Creates a query library
wcrtquery Creates a query
wgetquery Lists information about a query
wruninvquery Queries the database for inventory information and returns a list of object IDs and object labels that match the query criteria
wrunquery Runs a query and returns the results to either standard output or a file
wsetquery Edits the properties of a query
1–18 Version 3.7
Revision Control System (RCS) Commands
RDBMS Interface Module (RIM) Commands
Command Purpose
wci Checks in RCS revisions
wco Checks out RCS revisions
wident Identifies files
wrcs Changes RCS file attributes
wrcsdiff Compares RCS revisions
wrcsmerge Merges RCS revisions
wrlog Prints log messages and other information about RCS files
Command Purpose
wcrtrim Creates a RIM object
wgetrim Lists information about a RIM object
wrimtest Verifies a RIM object’s connectivity and functionality
wrimtrace Enables or disables tracing for RIM objects
wsetrim Changes the database information for a RIM object
wsetrimpw Sets the RIM password for a RIM object database
Tivoli Management Framework Reference Manual 1–19
Com
mands
Scheduler Commands
Task Library Commands
Command Purpose
wdelsched Removes jobs from the scheduler
wedsched Edits a job that currently exists in the scheduler
wenblsched Disables or enables scheduled jobs
wgetsched Retrieves information about jobs currently scheduled
wschedjob Schedules a job that exists in a task library
wstartsched Starts the Tivoli scheduler
Command Purpose
wcrtjob Creates a job in a task library
wcrttask Creates a task in a task library
wcrttlib Creates a task library
wdeljob Deletes a job from a task library
wdeltask Deletes a task from a task library
wdisttask Controls the distribution of task binaries for a task library
wgetjob Lists the properties of a job
wgettask Lists the properties of a task
1–20 Version 3.7
Miscellaneous Commands
wlstlib Lists the properties of a task library
wrunjob Runs a job in a task library
wruntask Runs a task in a task library
wsetjob Sets the properties of a job
wsettask Sets the properties of a task
wtaskabort Aborts a task transaction and rolls back any uncommitted changes
wtll Imports and exports task library definitions
Command Purpose
Command Purpose
tivoli Starts the Tivoli graphical user interface
waddicon Adds an icon to a Windows Program Manager group (Windows 95, and Windows NT only)
wbindmsg Retrieves a translated string from a local message catalog and binds any variables
wbkupdb Backs up and restores Tivoli databases
wcatcher Saves custom dialogs in Tivoli Management Framework or a Tivoli application before an upgrade to a new version of Tivoli Management Framework or the application
wcd Changes the current working collection
wchkdb Verifies and repairs the Tivoli database
Tivoli Management Framework Reference Manual 1–21
Com
mands
wchknode Verifies and updates references to a specific dispatcher number from parts of the Tivoli database
wdel Deletes objects from the Tivoli database
wdepot Manages MDist 2 repeater depots
wgetallinst Displays all instances of a resource type
wiconv Converts the characters or sequences of characters in a file from one code set to another code set
winstendpt Installs behavior for an endpoint resource type
winstruct Provides the Tivoli environment with information necessary to install and manage an application
winstruct_plus Creates Tivoli Application Management modules from Application Management Specification (AMS) files produced by the Tivoli Module Builder
winstruct_task Provides Tivoli Management Framework with information necessary to create tasks and dependencies for installing and managing an application
wlcftap Sets the properties of the Tivoli Authentication Package (TAP) on a Windows NT client
wln Links an object into a collection
wlocpath Returns the path for the localized file or directory
wls Lists a collection’s member objects
wlsinst Lists the products and patches installed in a TMR
wmdist Configures multiplexed distribution 2 (MDist 2) repeater parameters and manages distributions
Command Purpose
1–22 Version 3.7
wmdistgui Starts the multiplexed distribution 2 (MDist 2) graphical user interface from the managed node on which this command is run.
wmerge Performs a three-way file merge
wmrgaef Merge custom dialogs into Tivoli Management Framework or a Tivoli application after upgrading
wmv Moves objects between collections
wping Attempts to contact the object dispatcher on a host
wpwd Prints the current working collection
wrefresh Refreshes a Tivoli collection window
wrm Removes objects from a collection
wrmnode Removes a managed node from a Tivoli installation
wrpt Modifies the repeater system
wrunas Retrieves passwords and launches commands
wsetpkey Encrypts and stores passwords
wsupport Collects problem information from users to send to a customer support representative
wtemp Displays the name of the directory in which Tivoli products create temporary files
wtrace Provides information to debug methods
Command Purpose
idlarg
Tivoli Management Framework Reference Manual 1–23
Com
mands
idlarg Extracts individual arguments from an argument list returned by the idlinput command.
SYNOPSISidlarg element_offset [argument_list]
DESCRIPTIONThe idlarg command extracts individual arguments from an argument list returned by the idlinput command. This command can also be used to get the members of a constructed type. This command returns an exit code of 0 if successful. If an error occurs, this command exits with a nonzero code.
Arguments
element_offset Specifies the offset to the element in the argument list that should be extracted. The first element is at offset 1, the second element is at offset 2, and so on. element_offset must be a positive integer.
argument_list Specifies a list of arguments in cleartext format. If argument_list is not specified in the command line, idlarg reads from standard input until an EOF is encountered.
EXAMPLESThe following example extracts the in and inout arguments:interface test {
exception ex { long code; string reason; };struct s { long l; char c; };s op(in s a, inout s b, out s c) raises (ex);attribute long attr;
};
idlarg
1–24 Version 3.7
#! /bin/sh# shell implementation of test::op# Get the input/inout argumentsinargs=‘idlinput‘# $inargs may look like: "{1 ’z’} {2 ’w’}".# Now separate the in and inout arguments.arg_a=‘idlarg 1 $inargs‘arg_b=‘idlarg 2 $inargs‘# We can get to the fields of arg_a as followsarg_a_l=‘idlarg 1 $arg_a‘arg_a_c=‘idlarg 2 $arg_a‘# This will set arg_a_l to 1 and arg_a_c to# ’z’ respectively.
SEE ALSOidlcall, idlinput, idlresult, idlexception, idlattr
idlattr
Tivoli Management Framework Reference Manual 1–25
Com
mands
idlattr Gets or sets implementation attributes.
SYNOPSISidlattr –t [–s | –a | –g | –v] targetobject attrname typename [value]
DESCRIPTIONThe idlattr command gets or sets implementation (object) attributes. The –t argument indicates that the argument list contains the attribute type name; this argument is required. The –s and –g arguments indicate a set or get operation, respectively. If neither the –s nor –g argument is specified, the default is a set operation. The attrname option specifies the unscoped attribute name; this is the same unscoped attribute name as in the corresponding implementation construct. The typename option specifies the fully scoped attribute type. If a set operation is being performed, the value option is the cleartext value to which the attribute should be set. If this option is omitted in the command line, the cleartext value is read from standard input.
Arguments
–t Indicates that the argument list contains the type name of the attribute.
–s Specifies a set operation. This is the default.
–a Adds an attribute to the target object.
–g Specifies a get operation.
–v Specifies verbose mode. In verbose mode, exceptions are bound to messages and printed to standard output. The default is to write exceptions to standard output in cleartext format.
targetobject Specifies the target object for the operation. The target object should be specified in string format.
attrname Specifies the unscoped attribute name. This is the unscoped attribute name that is in the corresponding implementation construct.
typename Specifies the fully scoped type of the attribute.
idlattr
1–26 Version 3.7
value Specifies the cleartext value the attribute is to be set to. This option is valid only for a set operation (–s).
EXAMPLESThe following example shows the accessing of implementation attributes:interface test {exception ex { long code; string reason; };struct s { long l; char c; };s op(in s a, inout s b, out s c) raises (ex);attribute long attr;};
Assume the following implementation of an interface test: implementation class imp_test honors test {struct t { long l; };
attribute s attr1; // refers to test::sattribute t attr2;attribute unsigned long attr3; // define methods here
};
Assume 2001.1.15 is the object reference string to an instance of imp_test. Its physical attributes can be accessed or modified as follows: idlattr -t -g 2001.1.15 attr1 test::s// may print {1 ’z’}idlattr -t -s 2001.1.15 attr2 imp_test::t ’{20}’idlattr -t 2001.1.15 attr3 ulong 10
SEE ALSOidlcall
idlcall
Tivoli Management Framework Reference Manual 1–27
Com
mands
idlcall Provides a method of invoking Interface Definition Language (IDL) operations from the shell command line.
SYNOPSISidlcall [–T transtype] [–v] targetobject operationId [args]
DESCRIPTIONThe idlcall command invokes IDL operations from the shell command line. The transtype option can be used to specify a top-level transaction, a subtransaction, a revocable transaction, or no transaction. The targetobject option specifies the cleartext string representation of the target object reference. The operationId option specifies the operation name. The operation name can be specified as the fully scoped name separated by a doublecolon (Common Object Request Broker Architecture [CORBA] RepositoryId) or the operation name (as in the IDL description). The args option specifies any input or inout arguments. These arguments are listed in the same order as in the IDL description. This command writes the inout or output arguments and the result, if any, to standard output in cleartext format. If the idlcall invocation results in an exception, the exception is written to standard output. If an operation requires input or inout arguments but none are specified on the command line, this command reads input from standard input until an EOF is encountered.
Arguments
–T transtype Specifies a transaction type. This option can be one of the following:
top Top-level transaction
sub Subtransaction
revoke Revocable transaction
none No transaction
idlcall
1–28 Version 3.7
–v Specifies verbose mode. In verbose mode, exceptions are bound to messages and printed to standard output. The default is to write exceptions to standard output in cleartext format.
targetobject Specifies the cleartext string format of the target object’s object reference.
operationId Specifies the operation name. This can be the double-colon separated fully scoped name (CORBA RepositoryId) or the operation name (as in the IDL description). The first form is more efficient because it makes fewer remote calls, but the second form is simpler to use. For IDL attributes, the operation name is the attribute name prefix with _get_ or _set_ for a get or set operation, respectively.
args Specifies the input or inout arguments. If input or inout arguments are required but not specified on the command line, the idlcall command reads input from standard input until an EOF is encountered.
Exit Status
The idlcall command exits with a nonzero status if the invocation results in an exception (either in dispatching the call or raised by the method implementation). Otherwise, this command exits with 0. The exit status can be used to interpret the cleartext output.
EXAMPLESinterface test {
exception ex { long code; string reason; };struct s { long l; char c; };s op(in s a, inout s b, out s c) raises (ex);attribute long attr;
};
SEE ALSOidlattr
idlexception
Tivoli Management Framework Reference Manual 1–29
Com
mands
idlexception Raises exceptions for a shell method.
SYNOPSISidlexception [{exceptiontype scoped_exceptionname {exception_data}}]
DESCRIPTIONThe idlexception command is used to raise exceptions. The script must exit with a nonzero exit code if the script raises an exception. An exit code of 0 indicates a normal return.
Note: Do not use idlexception to raise an exception from an Tivoli Extended Interface Definition Language (TEIDL) command method. The Tivoli runtime will implicitly raise an exception from a command method if the command was terminated by a signal. A command method never raises an exception explicitly. Thus, a shell method refers to the TEIDL shell binding only.
Arguments
exceptiontype Specifies the exception type. This can be USER_EXCEPTION or SYSTEM_EXCEPTION.
scoped_exceptionname Specifies the fully qualified IDL exception name.
exception_data Indicates the cleartext representation of the exception structure fields. If the exception is empty, nothing is contained inside the inner parentheses. If idlexception is invoked without any command line arguments, the cleartext exception is read from standard input.
EXAMPLESinterface test {
exception ex { long code; string reason; };struct s { long l; char c; };s op(in s a, inout s b, out s c) raises (ex);attribute long attr;
};
idlexception
1–30 Version 3.7
#! /bin/sh# shell implementation of test::op# In doing some work, say we failed, and now# want to raise the test::ex exception.excep=‘idlexception ’{USER_EXCEPTION test::ex {"failed" 99}}’‘# the exception must be written to stdout.echo $excep# must exit with a nonzero statusexit 1
To raise a SYSTEM exception, enter the following: # Raise a standard exception (also let idlexception read
# from stdin)excp=‘idlexception <<!EOF{SYSTEM_EXCEPTION StExcep::BAD_PARAM {999 NO }}!EOF‘echo $excpexit 1
SEE ALSOidlcall, idlinput, idlresult, idlattr
idlinput
Tivoli Management Framework Reference Manual 1–31
Com
mands
idlinput Gets the input or inout arguments list to a shell method.
SYNOPSISidlinput
DESCRIPTIONThe idlinput command gets the input or inout arguments list (in cleartext format) to a shell method. The arguments are in the same order as in the Interface Definition Language (IDL) signature.
Note: Do not use idlinput with Tivoli Extended Interface Definition Language (TEIDL) command-style methods. A command method gets its input from the arguments list or standard input. Thus, a shell method refers to the EIDL shell binding only.
EXAMPLESThe following example accesses the inout arguments of the EIDL shell:interface test {
exception ex { long code; string reason; };struct s { long l; char c; };s op(in s a, inout s b, out s c) raises (ex);attribute long attr;
};
#! /bin/sh# shell implementation of test::op# Get the input/inout argumentsinargs=‘idlinput‘# $inargs may look like: "{1 ’z’} {2 ’w’}",# the first and the second pair of curly braces# contain the in argument (a) and the inout argument# (b) respectively. The method can now access each# individual argument or their fields using idlarg.# rest of the method goes here.
SEE ALSOidlcall, idlresult, idlexception, idlattr
idlresult
1–32 Version 3.7
idlresult Formats inout or output arguments or the result (if any) of a shell method.
SYNOPSISidlresult [arguments]
DESCRIPTIONThe idlresult command formats inout or output arguments or any result that is returned. The inout and output arguments must be in cleartext format and must be passed to this command in the same order that they appear in the Interface Definition Language (IDL) signature. The result, if any, follows. The arguments to be formatted may be specified as command line arguments to idlresult. Otherwise, idlresult reads the arguments from standard input until an EOF is encountered.
Note: Do not use idlresult with Tivoli Extended Interface Definition Language (TEIDL) command-style methods. A command method writes its output to standard output or standard error and no formatting is necessary. Thus, a shell method refers to the EIDL shell binding only.
EXAMPLESThe following example formats the inout arguments of the EIDL shell:interface test {
exception ex { long code; string reason; };struct s { long l; char c; };s op(in s a, inout s b, out s c) raises (ex);attribute long attr;
};
#! /bin/sh# shell implementation of test::op# do some work# return some hard coded values.b="{1 ’a’}"c="{2 ’b’}"retval="{3 ’c’}"# the order of arguments is inout(b), out(c) and# the return result. We could have also said:## all=‘idlresult <<!EOF
idlresult
Tivoli Management Framework Reference Manual 1–33
Com
mands
# $b# $c# $retval# !EOF# ‘#all=‘idlresult $b $c $retval‘# The results must be written to stdout.echo $all# A 0 exit code means a successful return from# a EIDL shell method.exit 0
SEE ALSOidlcall, idlinput, idlexception, idlattr
kadmin
1–34 Version 3.7
kadmin Network utility for Kerberos database administration.
SYNOPSISkadmin
DESCRIPTIONThis utility provides a unified administration interface to the Kerberos master database. Kerberos administrators use kadmin to register new users and services to the master database, and to change information about existing database entries. For instance, an administrator can use kadmin to change a user’s Kerberos password. A Kerberos administrator is a user with an “admin” instance whose name appears on one of the Kerberos administration access control lists.
The kadmin utility communicates over the network with the kadmind program, which runs on the machine housing the Kerberos master database. The kadmind creates new entries and makes modifications to the database.
When you enter the kadmin command, the program displays a message that welcomes you and explains how to ask for help. Then kadmin waits for you to enter commands (which are described below). It then asks you for your admin password before accessing the database.
Use the add_new_key (or ank for short) command to register a new principal with the master database. The command requires one argument, the principal’s name. You are asked to enter your admin password, and then you are prompted twice to enter the principal’s new password.
Use the add_new_instance (ani) command to add a new principal with a non-null instance to the master database. The command requires two arguments, the principal’s name and the principal’s instance. You are asked to enter your admin password, and then you are prompted twice to enter the principal’s new password.
Use the change_password (cpw) command to change a principal’s Kerberos password. The command requires one argument, the principal’s name. You are asked to enter your admin password, and then you are prompted twice to enter the principal’s new password.
kadmin
Tivoli Management Framework Reference Manual 1–35
Com
mands
Use the change_instance_key (cik) command to change the Kerberos password for a principal with a non-null instance. The command requires two arguments, the principal’s name and the principal’s instance. You are asked to enter your admin password, and then you are prompted twice to enter the principal’s new password.
Use the change_admin_password (cap) command to change your admin instance password. This command requires no arguments. It prompts you for your old admin password, and then prompts you twice to enter the new admin password.
Use the list_requests (lr) command to get a list of possible commands.
Use the help command to display the various help messages for kadmin. If entered without an argument, help displays a general help message. You can get detailed information on specific kadmin commands by entering help command_name.
To quit the program, type quit.
SEE ALSOkerberos, A Subsystem Utilities Package for UNIX by Ken Raeburn
BUGSkadmin currently does not allow addition, retrieval, or modification of principals with non-null instances.
AUTHORJeffrey I. Schiller, MIT (Massachusetts Institute of Technology) Project Athena
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice
kadmin
1–36 Version 3.7
appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kadmind
Tivoli Management Framework Reference Manual 1–37
Com
mands
kadmind Network daemon for Kerberos database administration.
SYNOPSISkadmind [–n] [–h] [–f filename] [–d dbname] [–a acldir]
DESCRIPTIONkadmind is the network database server for the Kerberos password-changing and administration tools.
Upon execution, it prompts the user to enter the master key string for the database. If the –n argument is specified, the master key is instead fetched from the master key cache file. If the –f filename option is specified, that file is used to hold the log information instead of the default.
If the –d dbname option is specified, that file is used as the database name instead of the default.
If the –a acldir option is specified, acldir is used as the directory in which to search for access control lists instead of the default.
If the –h argument is specified, kadmind prints a short summary of the permissible control arguments, and then exits.
When performing requests on behalf of clients, kadmind checks access control lists (ACLs) to determine the authorization of the client to perform the requested action. Currently three distinct access types are supported:
Addition (.add ACL file). If a principal is on this list, it may add new principals to the database.
Retrieval (.get ACL file). If a principal is on this list, it may retrieve database entries.
Note: A principal’s private key is never returned by the get functions.
Modification (.mod ACL file). If a principal is on this list, it may modify entries in the database.
A principal is always granted authorization to change its own password.
kadmind
1–38 Version 3.7
FILES
/kerberos/admin_server.syslog Default log file.
/kerberos Default access control list directory.
admin_acl.{add,get,mod} Access control list files (within the directory).
/kerberos/principal.pag, /kerberos/principal.dir Default DBM files containing a database.
/.k Master key cache file.
SEE ALSOkerberos, kpasswd, kadmin, acl_check
AUTHORDouglas A. Church, MIT Project Athena John T. Kohl, Project Athena/Digital Equipment Corporation
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kdb_destroy
Tivoli Management Framework Reference Manual 1–39
Com
mands
kdb_destroy Destroys a Kerberos key distribution center database.
SYNOPSISkdb_destroy
DESCRIPTIONkdb_destroy deletes a Kerberos key distribution center database.
The user is prompted to verify that the database should be destroyed. A response beginning with ‘y’ or ‘Y’ confirms deletion. Any other response aborts deletion.
DIAGNOSTICS
“Database cannot be deleted at /kerberos/principal” The attempt to delete the database failed (probably due to a system or access permission error).
“Database not deleted.” The user aborted the deletion.
FILES
/kerberos/principal.pag, /kerberos/principal.dir DBM files containing a database.
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to
kdb_destroy
1–40 Version 3.7
distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
SEE ALSOkdb_init
kdb_edit
Tivoli Management Framework Reference Manual 1–41
Com
mands
kdb_edit Kerberos key distribution center database editing utility.
SYNOPSISkdb_edit [–n]
DESCRIPTIONkdb_edit is used to create or change principals stored in the Kerberos key distribution center (KDC) database.
When executed, kdb_edit prompts for the master key string and verifies that it matches the master key stored in the database. If the –n argument is specified, the master key is instead fetched from the master key cache file.
After the master key has been verified, kdb_edit begins a prompt loop. The user is prompted for the principal and instance to be modified. If the entry is not found, the user may create it. After an entry is found or created, the user may set the password, expiration date, maximum ticket lifetime, and attributes. Default expiration dates, maximum ticket lifetimes, and attributes are presented in brackets; if the user presses Enter, the default is selected. There is no default password. The password RANDOM is interpreted specially, and if entered, the user may have the program select a random DES key for the principal.
Upon successfully creating or changing the entry, Edit O.K. is printed.
DIAGNOSTICS
“verify_master_key: Invalid master key, does not match database.” The master key string entered was incorrect.
FILES
/kerberos/principal.pag, /kerberos/principal.dir DBM files containing a database.
/.k Master key cache file.
kdb_edit
1–42 Version 3.7
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kdb_init
Tivoli Management Framework Reference Manual 1–43
Com
mands
kdb_init Initializes a Kerberos key distribution center database.
SYNOPSISkdb_init [realm]
DESCRIPTIONkdb_init initializes a Kerberos key distribution center database, creating the necessary principals.
If the optional realm argument is not present, kdb_init prompts for a realm name (defaulting to the definition in /usr/include/krb.h). After determining the realm to be created, it prompts for a master key password. The master key password is used to encrypt every encryption key stored in the database.
DIAGNOSTICS
“/kerberos/principal: File exists” An attempt was made to create a database on a machine that already had an existing database.
FILES
/kerberos/principal.pag, /kerberos/principal.dir DBM files containing a database.
/usr/include/krb.h Include file defining default realm.
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice
kdb_init
1–44 Version 3.7
appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
SEE ALSOkdb_destroy
kdb_util
Tivoli Management Framework Reference Manual 1–45
Com
mands
kdb_util Kerberos key distribution center database utility.
SYNOPSISkdb_util operation filename
DESCRIPTIONkdb_util allows the Kerberos key distribution center (KDC) database administrator to perform utility functions on the database.
operation must be one of the following:
load Initializes the KDC database with the records described by the text contained in the file filename. Any existing database is overwritten.
dump Dumps the KDC database into a text representation in the file filename.
slave_dump Performs a database dump like the dump operation, and additionally creates a semaphore file, which signals the propagation software that an update is available for distribution to slave KDC databases.
new_master_key Prompts for the old and new master key strings, and then dumps the KDC database into a text representation in the file filename. The keys in the text representation are encrypted in the new master key.
convert_old_db Prompts for the master key string, and then dumps the KDC database into a text representation in the file filename. The existing database is assumed to be encrypted using the old format (encrypted by the key schedule of the master key); the dumped database is encrypted using the new format (encrypted directly with master key).
DIAGNOSTICS
“verify_master_key: Invalid master key, does not match database.” The master key string entered was incorrect.
kdb_util
1–46 Version 3.7
FILES
/kerberos/principal.pag, /kerberos/principal.dir DBM files containing a database.
filename.ok Semaphore file created by slave_dump.
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kdestroy
Tivoli Management Framework Reference Manual 1–47
Com
mands
kdestroy Destroy Kerberos tickets.
SYNOPSISkdestroy [–f] [–q]
DESCRIPTIONThe kdestroy utility destroys the user’s active Kerberos authorization tickets by writing zeros to the file that contains them. If the ticket file does not exist, kdestroy displays a message to that effect.
After overwriting the file, kdestroy removes the file from the system. The utility displays a message indicating the success or failure of the operation. If kdestroy is unable to destroy the ticket file, the utility warns you by making your terminal beep.
Arguments
–f Status message does not display.
–q kdestroy terminal does not beep if tickets are not destroyed.
FILESKRBTKFILE environment variable if set; otherwise, /tmp/tkt[uid].
SEE ALSOkerberos, kinit, klist
kerberos
1–48 Version 3.7
kerberos Introduction to the Kerberos authentication service.
DESCRIPTIONKerberos authenticates individual users in a network environment. After authenticating yourself to Kerberos, you can use network utilities such as rlogin, rcp, and rsh without having to present passwords to remote hosts and without having to use .rhosts files. These utilities work without passwords only if the remote machines you deal with support the Kerberos system.
Tivoli can use Kerberos to authenticate Tivoli objects in a distributed management environment.
Before you can use Kerberos, you must make sure that you have been added to the Kerberos database. Use the kinit command. This command tries to log you in to the Kerberos system. kinit prompts you for a user name and password. Enter your user name and password. If you can log in without a message, you are registered in the Kerberos database.
If you enter your user name and kinit responds with this message, see your system administrator:
Principal unknown (kerberos) you haven’t been registered as a
Kerberos user. See your system administrator.
A Kerberos name contains three parts:
■ principal name—Usually a user’s or service’s name.
■ instance—In the case of a user, usually null. Some users may have privileged instances, however, such as root or admin. In the case of a service, the instance is the name of the machine on which it runs; for example, an rlogin service can run on machine ABC, which is different from the rlogin service running on the machine XYZ.
■ realm—Corresponds to the Kerberos service providing authentication for the principal. For example, at MIT there is a Kerberos running at the Laboratory for Computer Science and one running at Project Athena.
When writing a Kerberos name, the principal name is separated from the instance (if not null) by a period, and the realm (if not the local realm)
kerberos
Tivoli Management Framework Reference Manual 1–49
Com
mands
follows, preceded by an “@” sign. The following are examples of valid Kerberos names:
[email protected]@athena.mit.edu
When you authenticate yourself with Kerberos through the kinit command, Kerberos gives you an initial Kerberos ticket. (A Kerberos ticket is an encrypted protocol message that provides authentication.) Kerberos uses this ticket for network utilities such as rlogin and rcp. The ticket transactions are done transparently, so you do not have to manage them.
Tickets, however, expire. Privileged tickets, such as root instance tickets, expire in a few minutes. Tickets that carry more ordinary privileges can be good for several hours or a day, depending on the installation’s policy. If your login session extends beyond the time limit, you will have to reauthenticate yourself to Kerberos to get new tickets. Use the kinit command to reauthenticate yourself.
If you use the kinit command to get your tickets, be sure to use the kdestroy command to destroy your tickets before you end your login session. If you put the kdestroy command in your .logout file, your tickets will be destroyed automatically when you log out. See the kinit and kdestroy commands for more information.
Kerberos supports the following network services: rlogin, rsh, and rcp.
SEE ALSOkdestroy, kinit, klist, kpasswd
BUGSKerberos will not do authentication forwarding. In other words, if you use rlogin to log in to a remote host, you cannot use Kerberos services from that host until you authenticate yourself explicitly on that host. Although you may need to authenticate yourself on the remote host, be aware that when you do so, rlogin sends your password across the network in cleartext.
kerberos
1–50 Version 3.7
AUTHORSteve Miller, MIT Project Athena/Digital Equipment Corporation, Clifford Neuman, MIT Project Athena
The following people helped out on various aspects of the system:
■ Jeff Schiller designed and wrote the administration server and its user interface, kadmin. He also wrote the dbm version of the database management system.
■ Mark Colan developed the Kerberos versions of rlogin, rsh, and rcp as well as contributing work on the servers. These versions of rlogin, rsh, and rcp were further modified by Tivoli Systems Inc.
■ John Ostlund developed the Kerberos versions of passwd and userreg.
■ Stan Zanarotti pioneered Kerberos in a foreign realm (LCS), and made many contributions based on that experience.
Many people contributed code and useful ideas, including Jim Aspnes, Bob Baldwin, John Barba, Richard Basch, Jim Bloom, Bill Bryant, Rob French, Dan Geer, David Jedlinsky, John Kohl, John Kubiatowicz, Bob McKie, Brian Murphy, Ken Raeburn, Chris Reed, Jon Rochlis, Mike Shanzer, Bill Sommerfeld, Jennifer Steiner, Ted Ts’o, and Win Treese.
Note: Additional revision of this version was performed by Tivoli Systems to support the Tivoli software. The following functions were modified: kerberos, kdb_edit, kdb_init, and kdb_destroy.
RESTRICTIONSCopyright © 1985, 1986, 1989 Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the
kerberos
Tivoli Management Framework Reference Manual 1–51
Com
mands
name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kinit
1–52 Version 3.7
kinit Kerberos login utility.
SYNOPSISkinit [–irvl]
DESCRIPTIONThe kinit command is used to log in to the Kerberos authentication and authorization system. Only registered Kerberos users can use the Kerberos system. For information about registering as a Kerberos user, see the kerberos command.
When you use kinit without options, you are prompted for your user name and Kerberos password, and kinit tries to authenticate your login with the local Kerberos server.
If Kerberos authenticates the login attempt, kinit retrieves your initial ticket and puts it in the ticket file specified by your KRBTKFILE environment variable. If this variable is undefined, your ticket is stored in the tmp directory, in the file tktuid, where UID specifies your user identification number.
Always use the kdestroy command to destroy active tickets before you end your login session. If you put the kdestroy command in your .logout file, your tickets are destroyed automatically when you log out.
Arguments
–i Specifies that you are to be prompted for a Kerberos instance.
–v Specifies verbose mode. kinit prints the name of the ticket file used, and a status message indicating the success or failure of your login attempt.
–l kinit prompts you for a ticket lifetime in minutes. The value must be between 5 and 1275 minutes.
SEE ALSOkerberos, klist
klist
Tivoli Management Framework Reference Manual 1–53
Com
mands
klist Lists currently held Kerberos tickets.
SYNOPSISklist [–s –t] [–file filename] [–srvtab]
DESCRIPTIONklist prints the name of the tickets file and the identity of the principal the tickets are for (as listed in the tickets file), and lists the principal names of all Kerberos tickets currently held by the user, along with the issue and expiration time for each authenticator. Principal names are listed in the form name.instance@realm, with the ‘.’ omitted if the instance is null, and the ‘@’ omitted if the realm is null.
Arguments
–s Specifies that issue and expiration times, the name of the tickets file, or the identity of the principal are not to be printed.
–t klist checks for the existence of a nonexpired ticket-granting ticket in the ticket file. If one is present, it exits with status 0; if not, it exits with status 1. No output is generated when –t is specified.
–file filename Specifies filename as the ticket file. Otherwise, if the KRBTKFILE environment variable is set, it is used. If this environment variable is not set, the file /tmp/tkt[uid] is used, where uid is the current user ID of the user.
–srvtab Specifies that the file is to be treated as a service key file. The names of the keys contained in the file display.
FILES
/etc/krb.conf File containing the name of the local realm.
/tmp/tkt[uid] Default ticket file ([uid] is the decimal UID of the user).
/etc/srvtab Default service key file.
klist
1–54 Version 3.7
SEE ALSOkerberos, kinit, kdestroy
BUGSWhen reading a file as a service key file, little error checking is performed.
RESTRICTIONSCopyright ©1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kpasswd
Tivoli Management Framework Reference Manual 1–55
Com
mands
kpasswd Changes a user’s Kerberos password.
SYNOPSISkpasswd [–h] [–n name] [–i instance] [–r realm] [–u username[.instance@realm]]
DESCRIPTIONThe kpasswd command is used to change a Kerberos principal’s password.
The utility prompts for the current Kerberos password (printing the name of the principal for which it intends to change the password), which is verified by the Kerberos server. If the old password is correct, the user is prompted twice for the new password. A message is printed indicating the success or failure of the password changing operation.
Arguments
–h Prints a brief summary of the arguments.
–n name Specifies that name is to be used as the principal name rather than the user name of the user running kpasswd. (This is determined from the ticket file if it exists; otherwise, it is determined from the UNIX user ID.)
–i instance Specifies that instance is to be used as the instance rather than a null instance.
–r realm Specifies that realm is to be used as the realm rather than the local realm.
–u username[.instance@realm] Specifies a fully qualified Kerberos principal.
SEE ALSOkerberos, kinit, passwd(1)
kpasswd
1–56 Version 3.7
BUGSkpasswd does not handle names, instances, or realms with special characters in them when the –n, –i, or –r arguments are used. If the –u argument is used, however, any valid full name is accepted.
If the principal whose password you are trying to change does not exist, you will not receive a message until after you have entered the old password.
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
ksrvtgt
Tivoli Management Framework Reference Manual 1–57
Com
mands
ksrvtgt Fetches and stores the Kerberos ticket-granting ticket using a service key.
SYNOPSISksrvtgt name instance [[realm] srvtab]
DESCRIPTIONksrvtgt retrieves a ticket-granting ticket with a lifetime of 5 minutes for the principal name.instance@realm (or name.instance@localrealm if realm is not supplied on the command line), decrypts the response using the service key found in srvtab (or in /etc/srvtab if srvtab is not specified on the command line), and stores the ticket in the standard ticket cache.
This command is intended primarily for use in shell scripts and other batch-type facilities.
DIAGNOSTICS“Generic kerberos failure (kfailure)” can indicate a range of problems, the most common of which is the inability to read the service key file.
FILES
/etc/krb.conf File containing the name of the local realm.
/tmp/tkt[uid] The default ticket file.
/etc/srvtab The default service key file.
SEE ALSOkerberos, kinit, kdestroy
ksrvtgt
1–58 Version 3.7
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
kstash
Tivoli Management Framework Reference Manual 1–59
Com
mands
kstash Stashes the Kerberos key distribution center database master key.
SYNOPSISkstash
DESCRIPTIONkstash saves the Kerberos key distribution center (KDC) database master key in the master key cache file.
The user is prompted to enter the key, to verify the authenticity of the key and the authorization to store the key in the file.
DIAGNOSTICS
“verify_master_key: Invalid master key, does not match database.” The master key string entered was incorrect.
“kstash: Unable to open master key file” The attempt to open the cache file for writing failed (probably due to a system or access permission error).
“kstash: Write I/O error on master key file” The write(2) system call returned an error while kstash was attempting to write the key to the file.
FILES
/kerberos/principal.pag, /kerberos/principal.dir DBM files containing a database.
/.k Master key cache file.
RESTRICTIONSCopyright © 1989 by the Massachusetts Institute of Technology.
Export of this software from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
kstash
1–60 Version 3.7
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.
lcfd
Tivoli Management Framework Reference Manual 1–61
Com
mands
lcfdProvides configuration information to the endpoint daemon (lcfd), including login parameters, port numbers, and debugging information.
SYNOPSISlcfd [–b lib_dir] [–C dir_name] [–d level] [–D option=value][–g address[+port] [:address [+port]…]] [–H] [–i] [–l filename] [–n endpoint_label] [–p ep_gw_port] [–P ep_port] [–r svc_name] [–s] [–x protocol_name]
DESCRIPTIONThe lcfd command provides configuration information to the endpoint daemon (lcfd), including login parameters, port numbers, and debugging information. It can also start the endpoint daemon (lcfd) installed on an endpoint. UNIX endpoints can use the lcfd.sh script to start and stop the endpoint (see lcfd.sh). On Windows NT and Windows 2000, you can use the –i argument to install the daemon as a service on Windows NT and Windows 2000. The –r argument removes an existing service from the Windows NT Service Manager. To view the usage statement for this command, enter lcfd –s –D?. When using IPX to connect to endpoints, only the following platforms are supported: NetWare, Windows 95, Windows 98, Windows NT, and Windows 2000.
Authorization
No Tivoli authorization role is required.
Arguments
–b lib_dir Specifies the path to the configuration library, which contains the shared libraries required by an endpoint. This argument does not apply to NetWare.
–C dir_name Specifies the name of the endpoint’s current working directory. This directory contains configuration files needed for startup and the method cache.
–d level Defines the level of debug messages written to the lcfd.log file. The default value is 1. The following are valid entries:
lcfd
1–62 Version 3.7
0 No message logging
1 Minimal logging (default)
2 Tracing and moderate output
3 Detailed information and tight loops
4 Data
Note: Level 1 is the default value. Level 4 message logging generates a large number of messages. Level 2 or 3 is recommended for troubleshooting.
–D option=value Reconfigures the endpoint during startup using one or more of the following options. Configuration information is stored in the last.cfg file on the endpoint. Some of these options can also be set with command line arguments.
? Displays the usage statement for this command.
address_notif_interval=seconds For Dynamic Host Configuration
Protocol (DHCP) environments, specifies an endpoint timeout interval to wake up from its idle state and attempt to notify the gateway of its current IP address. This argument is only for endpoints that might change IP addresses without the endpoint daemon restarting. The recommended value for this argument is 300 seconds. The default value for this option is 0, meaning that the endpoint daemon will not notify the gateway.
bcast_disable=1 | 0 Disables the User Datagram Protocol (UDP) or IPX broadcast when set to 1. If you set this option to 1, you must use
lcfd
Tivoli Management Framework Reference Manual 1–63
Com
mands
the lcs.login_interfaces option. IPX extended broadcast uses the RIP protocol, and is able to send login packets within a 5-hops radius.
cache_limit=max_size Specifies the maximum size of the method cache. After this maximum size is reached, the least recently used methods are deleted to make room for current methods.
cache_loc=cache Identifies or changes the name of the method cache created and maintained on the endpoint. This argument can also be used to change the location of the method cache when submitted with a full path name.
config_path=last.cfg Identifies the absolute path to the last.cfg configuration file. Editing this option is not recommended.
debug_flags=debug_level Enables the user to attach a debug tool to a running method. Editing this option is not recommended.
gateway_port=port_number Identifies the port on which the gateway monitors endpoint communications. The default value is 9494. This option can also be set using the lcfd –p command.
http_disable=value Specifies the level of functionality for the Web browser accessible on the endpoint. By default, the Web browser is fully enabled and can be used
lcfd
1–64 Version 3.7
remotely for configuration of the endpoint (value=0). If you set value=1, the Web browser allows viewing of endpoint configuration data, but changing endpoint configuration from the browser is disallowed. If you set value=2, the endpoint daemon will not respond to Web browser (http) requests.
interp=interp_type Identifies the interpreter type of the endpoint. Editing this option is not recommended.
lcfd_port=port_number Identifies the port on which the endpoint daemon (lcfd) monitors gateway communications. The default value is 9495. This option can also be set using lcfd –P.
lcfd_alternate_port=port_number Identifies an alternate port on which
the endpoint daemon (lcfd) monitors gateway communication if lcfd cannot contact its default port (specified by lcfd –P) during startup. The default value is 9496.
local_ip_address=IP_address For endpoints with multiple IP
addresses, allows connections on the specified IP_address. If the local_ip_address option is specified, the endpoint will bind to the provided address rather than 0.0.0.0, and connections will only be accepted on that interface.
lcfd
Tivoli Management Framework Reference Manual 1–65
Com
mands
lcs.gateway_address=IP_address or IPX_address Changes the login gateway after the endpoint has successfully logged in. If the gateway has not previously logged in, use the lcs.login_interfaces option to provide one or more gateways through which the endpoint may log in. For NetWare, Windows NT, Windows 95, Windows 98, and Windows 2000 endpoints using IPX, to login to a gateway located outside a 5-hops radius, you must specify the IPX address (not host name).
lcs.login_interfaces=address[+port][:address[+port]]…
Specifies the IP address or host name (or IPX address or server name) and port number of one or more gateways to which an endpoint will send its login packet. This option is required for the endpoint to log in to a gateway on a different subnet or to log in to a specific gateway when two or more exist on a subnet. If your gateways and endpoints are separated by a network address translation (NAT) device, specify host names instead of IP addresses. Multiple addresses must be separated by colons. You can also use the –g argument to list one or more gateways.
Note: This option does not specify the gateway to which an endpoint is ultimately assigned. The endpoint manager determines gateway selection and assignment. If the endpoint has successfully
lcfd
1–66 Version 3.7
logged in to a gateway, use the lcs.gateway_address option to change the gateway.
logfile=full_path Identifies the absolute path to the file in which status messages are logged. The default log file is lcfd.log. Editing this option is not recommended.
Note: Tivoli recommends using the –l argument to change the name of the log file.
login_interval=seconds Specifies the waiting period before an endpoint executes another login attempt. The default is 1800 seconds (30 minutes).
lcs.machine_name=endpoint_label Identifies the endpoint label as shown in wlookup or wep. You can also use the –n argument to identify an endpoint label.
lcs.machine_unique_id=ID_number Identifies the unique identification of the endpoint.
log_queue_size=max_size Specifies the maximum amount of memory (measured in bytes) used for the log queue. Only LogQ messages are sent to the log queue. If an exception occurs, the entire queue is printed to the screen. The valid range is 1024 through 102400.
log_size=max_size Specifies the maximum size (in bytes) of the log file. The valid range is 10240 through 10240000.
lcfd
Tivoli Management Framework Reference Manual 1–67
Com
mands
log_threshold=debug_level Identifies the level of debug logging. This option can also be set using the –d argument.
protocol=TCPIP | IPX Identifies the protocol on which the endpoint daemon (lcfd) monitors gateway communications. The default value is TCPIP. This option can also be set using the –x argument.
run_dir=dir_name Identifies the directory from which the endpoint daemon will run. Editing this option is not recommended.
run_timeout=seconds This value is no longer used. The udp_interval is now used to specify the wait time (in seconds) before a communication timeout occurs following a successful login.
start_timeout=seconds Specifies the wait time (in seconds) before a communication timeout occurs during login. The default value is 120.
start_delay Delays lcfd startup in cases where an endpoint and a gateway coexist on the same machine. If start_delay is not used in the above circumstances, endpoint login either takes a long time, or it may not occur at all.
udp_attempts=number Specifies the number of times an endpoint will transmit an initial login request. The default value is 6.
lcfd
1–68 Version 3.7
udp_interval=seconds Specifies the number of seconds between endpoint initial login request attempts. The default value is 300.
–g address[+port] [:address [+port]]… If the endpoint uses TCPIP, this option specifies the IP address or host name and, optionally, the port number of one or more gateways to which an endpoint sends its login packet. If the endpoint uses SPX/IPX, this option specifies the IPX address or server name and port number of one or more gateways to which an endpoint sends its login packet. The default port number is 9495. This option is required for the endpoint to log in to a gateway on a different subnet or to log in to a specific gateway when two or more exist on a subnet. If your gateways and endpoints are separated by a network address translation (NAT) device, specify host names instead of IP addresses. Multiple addresses must be separated by colons. For NetWare, Windows NT, Windows 95, Windows 98, and Windows 2000 endpoints to login to a gateway located outside a 5-hops radius, you must specify the IPX address (not server name).
–H In OS/2 only, removes lcfd.exe from the task list to prevent users from inadvertently killing the lcfd daemon. This argument does not hide the process from other means of detection such as PSPM2, pstat, or KILLFEATUREENABLE=YES in the config.sys file.
–i Installs the endpoint software as a Windows NT and Windows 2000 service on the specified endpoint. Valid on Windows NT and Windows 2000 only.
–l filename Specifies the name of the log file to which status and error messages are written. The default file name is lcfd.log.
lcfd
Tivoli Management Framework Reference Manual 1–69
Com
mands
–n endpoint_label Identifies the endpoint label as shown in wlookup or wep. Netware, Windows and OS/2 endpoints communicating over TCP/IP use the machine’s hostname as the default. NetWare endpoints using IPX use the server name as the default. Windows NT, Windows 95, Windows 98, and Windows 2000 endpoints using IPX use the computer name as the default.
–p ep_gw_port Specifies the port number on which the gateway monitors endpoint communications.
–P ep_port Sets the port number on which the endpoint monitors gateway communications.
–r svc_name Removes an existing Windows NT service from the Service Manager. If used on Windows 95, removes all instances of lcfd. Valid for Windows NT, Windows 2000, Windows 95, and Windows 98 only.
–s Starts an endpoint as a console application, printing all messages to the screen and to the endpoint log file. If used on Windows 95 and Windows 98, this argument prints all messages in the debug window and the log file. OS/2 and NetWare ignore this argument.
–x protocol_name Specifies the protocol the endpoint will use to communicate with its assigned gateway. Supported protocols are TCP/IP and IPX. The default is TCP/IP.
EXAMPLES
1. The following example starts the local endpoint using configuration information contained in the last.cfg file:
lcfd
2. The following example starts the endpoint as a service on the local machine and sets the debug level to 3, which causes the endpoint to log all messages to the lcfd.log file:
lcfd -i -d 3
lcfd
1–70 Version 3.7
3. The following example restarts the local Windows NT endpoint. The endpoint will log in to a gateway outside its subnet (with host name zeus) on port 27246. The –p argument indicates both the endpoint and gateway will use port 27246.
lcfd -p 27246 -g zeus+9494
4. The following example starts the local endpoint as a service and specifies that it will use SPX/IPX as a protocol. It also specifies that it will log in to a gateway with the specified IPX address, listening to a specified port.
lcfd -x IPX -g 4132AF12.000000000001+41204 -i
SEE ALSOlcfd.sh
lcfd.sh
Tivoli Management Framework Reference Manual 1–71
Com
mands
lcfd.shStarts or stops the endpoint daemon (lcfd) on UNIX endpoints.
SYNOPSISlcfd.sh {start | stop} [lcfd_ arguments]
DESCRIPTIONThe lcfd.sh command is a wrapper for the lcfd command. lcfd.sh contains the links to platform-specific shared libraries required on UNIX endpoints. lcfd.sh takes the same arguments as the lcfd command and resides in LCF_DATDIR. These arguments are then passed to lcfd when it is invoked. See the lcfd command for a detailed explanation of the lcfd options.
The lcfd.sh command is run locally on UNIX machines in LCF_DATDIR.
Authorization
No Tivoli authorization is required.
Arguments
start Starts the endpoint daemon (lcfd).
stop Stops the endpoint daemon (lcfd).
lcfd_arguments See lcfd command for a detailed explanation of the lcfd options.
EXAMPLESThe following example is run locally on a UNIX endpoint and stops the endpoint daemon on that machine: lcfd.sh stop
SEE ALSOlcfd
logls
1–72 Version 3.7
logls Creates a readable version of a transaction log file.
SYNOPSISlogls [–Dofls] [–k dir] [–m maxdlen] logname…
DESCRIPTIONThe logls command creates a readable version of the specified transaction log files. It is primarily a diagnostic tool for debugging the transaction manager. Customer Support may ask you to run this command if a severe problem is encountered.
The oserv daemon’s transaction log file is odb.log. This file is located in the database directory.
If the oserv daemon is running, you may want to shut it down or synchronize the database. The log snapshot may be incomplete with respect to any currently running transactions.
You can run odadmin db_sync to flush the log file.
Authorization
You must have read permission for the log files you want to list.
Arguments
–D Prints the data in the log records.
–o Lists only the “old pages” log records.
–f Lists only the “forward” log records.
–l Prints the log headers.
–s Lists only the log headers. No “forward” or “old pages” log records are listed.
–k dir Specifies the directory to prepend to each log file name.
–m maxdlen Specifies the maximum amount of data to dump. This option should be used with the –D argument. If the maxdlen option is not specified, the default amount is 64 bytes.
logls
Tivoli Management Framework Reference Manual 1–73
Com
mands
logname… Specifies the name of the log file to be processed. You can specify multiple log files.
EXAMPLESThe following example creates a readable version of a specified transaction log file:logls –k /var/spool/Tivoli/myhost.db odb.log
This example might produce entries such as the following: Database update records:old page 0 8248insert "0.0.0"insert <0.0.0\x00.attr._bootcount\x00>{0:0,0:0,1:0} replace <0.0.0\x00.attr._ids\x00>Database transaction state transitions:prepare transaction {0:0,0:0,1:0}complete transaction {0:0,0:0,1:0}abort transaction {202020:1,202020:1,1:75}Database event and undo callbacks registered:{2020201,202020:1,1:61} undo [1:0:286748945] 2000.1.3 \undo_callback{2020201,202020:1,1:61} Event-prepare 2000.1.3 prepare_callback{2020201,202020:1,1:61} Event-complete 2000.1.3 commit_callback{2020201,202020:1,1:61} Event-abort 2000.1.3 abort_callback
SEE ALSOtmstat, tmcmd
objcall
1–74 Version 3.7
objcall Performs an object call from the shell.
SYNOPSISobjcall [–a] [–b] [–c group:role:…] [–e] [–F filedescriptor] [–k len] [–n] [–p port] [–s] [–T transtype] oid method [arg…]
DESCRIPTIONThe objcall command requests the specified object to run the specified method with zero or more arguments. The method’s standard output and standard error are sent to the objcall command’s standard output and standard error. This command exits with the method’s exit code. This command is only used for non-IDL (Interface Definition Language) methods.
Authorization
No role is required to run the objcall command itself, but you must have the roles required by the method that is specified as an argument to the objcall command.
Arguments
–a Performs the object call asynchronously.
–b Passes the objcall command’s standard input to the method’s standard input. If this argument is not specified, the method gets an empty standard input.
–c group:role:… Performs the object call with the specified group and specified roles. The caller can only specify roles that the caller has. If this option is not specified, the method runs with all of the caller’s roles.
–e Passes the objcall command’s environment as the method’s environment. If this argument is not specified, the method is given a default miniature environment.
objcall
Tivoli Management Framework Reference Manual 1–75
Com
mands
–F filedescriptor Specifies the file descriptor number to which to write status information.
–k len Reads the number of bytes specified by the len option from standard input for the key value. If the –k argument is not specified, no key is used.
–n Starts the method and exits the objcall command asynchronously without waiting for the method to return results.
–p port Specifies the local object dispatcher port number.
–s Creates iom keys for sending input and output to and from a method. This argument should be specified only if the method being called expects these keys as input.
–T transtype Specifies a transaction type. This option can be one of the following:
top Top-level transaction
sub Subtransaction
revoke Revocable transaction
none No transaction
oid Specifies the object ID of the object that is to run the method.
method Specifies the method to be run.
arg… Specifies one or more arguments for the method. If this option is not specified, the method does not get any arguments.
Note: If both the –b and –k arguments are specified, the key (–k len) is read first.
EXAMPLESThe following example invokes the echo method on the local base object “0.0.0” with no input. No output is produced. objcall 0.0.0 echo
objcall
1–76 Version 3.7
SEE ALSOidlcall
odadmin
Tivoli Management Framework Reference Manual 1–77
Com
mands
odadmin Manages object dispatchers.
SYNOPSISodadmin [option [suboption]]
DESCRIPTIONThe odadmin command provides a command line interface (CLI) to many oserv run-time configuration settings and management operations. The list of supported functions includes options for the following:
■ Allowing or disallowing client installations
■ Synchronizing object databases
■ Getting or setting object dispatcher environments
■ Listing information about object dispatchers
■ Reexecuting object dispatchers
■ Performing remote region operations
■ Setting encryption levels and passwords
■ Setting down-host checking options
■ Starting and shutting down object dispatchers
■ Enabling or disabling Kerberos authentication
■ Adding or changing platform and application license keys
It is recommended that you back up all object databases before you use the odadmin command to change the low-level configuration of a Tivoli Management Region (TMR). There may be better methods (using the Tivoli desktop or CLI commands other than the odadmin command) to perform some of the operations that the odadmin command allows you to perform. If you are not explicitly familiar with the implications of the odadmin command, call your Customer Support provider before attempting to perform any odadmin operations.
odadmin
1–78 Version 3.7
Arguments
allow_client_install TRUE | FALSE Sets an installation flag to permit or disallow adding additional object dispatchers to the local region. You must have the super or senior role to run this option.
allow_dynamic_ipaddr TRUE | FALSE Enables or disables dynamic Internet Protocol (IP) address assignment support (Dynamic Host Configuration Protocol [DHCP]) within the local TMR. The default value is FALSE.
db_sync [od… | clients | all] Flushes the object database state to disk. You can flush the specified object databases (od), all client object databases (clients), or all object databases (all) to disk. You must have the super or senior role to run this option.
environ Gets or sets the method environment for specific object dispatchers. The method environment is the environment variables that are set inside the process of the method when the method executes. Default environment variables are set in addition to the user-specified variables displayed when using this option. You must have the super or senior role to run this option.
The following suboptions are available with the environ option:
get [od… | clients | all] Gets the method environment for one or more specific object dispatchers (od…), all client object dispatchers (clients), or all object dispatchers (all).
odadmin
Tivoli Management Framework Reference Manual 1–79
Com
mands
set [od… | clients | all] Sets the method environment for one or more specific object dispatchers (od…), all client object dispatchers (clients), or all object dispatchers (all). The method environment is read from standard input.
get_port_range Gets the port range setting for interobject message (IOM) channel communication ports and Tivoli communication between managed nodes. To set the port range, use the set_port_range argument.
get_rpc_max_threads Retrieves the maximum number of concurrent remote procedure call threads handled by the dispatcher. You can reset this number with the set_rpc_max_threads option.
help [option] When invoked with no option, gives top-level help about the available options for the odadmin command. If an option is specified, gives help for the specified option. If no help is available for the specified option, the top-level help menu is displayed. You can run this option with any role.
odinfo [od… | clients | all] Provides information about specific object dispatchers (od…), all client object dispatchers (clients), or all object dispatchers (all) in an installation. odinfo is the default option if you invoke the odadmin command without specifying any options. You must have the super, senior, admin, or user role to run this option.
The odinfo option provides the following object dispatcher information:
Region The region the object dispatcher is located in.
Dispatcher The object dispatcher ID.
odadmin
1–80 Version 3.7
Interpreter Type The type of method interpreter for the object dispatcher.
Database directory The path name of the object dispatcher’s database directory.
Install directory The path name of the object dispatcher’s installation directory.
Inter-dispatcher encryption level The encryption level this object dispatcher uses for communication with other object dispatchers.
Kerberos in use Indicates if the object dispatcher is using Kerberos authentication.
Remote Client Login Allowed Indicates if Tivoli Desktop for Windows may connect to this object dispatcher.
Install library path (UNIX only) The shared library search path specified at installation time.
oserv version string The object dispatcher’s version information.
Tivoli copyright info The Tivoli copyright information.
For a TMR server, the following information is also provided:
State flags in use Indicates whether down host information is cached (TRUE) or whether a host is tried each time (FALSE).
odadmin
Tivoli Management Framework Reference Manual 1–81
Com
mands
State checking in use Indicates whether the host state information is kept up-to-date with polling (TRUE) or collected implicitly (FALSE).
State checking every x seconds Indicates the interval at which state checking is performed.
If you do not specify any object dispatcher numbers or the clients or all parameter, the odinfo option returns information about the local object dispatcher.
odlist [suboption] Lists or edits information about the dispatchers in an installation. You must have the super or senior role to run this option. If you specify the odlist option without any suboptions, the following information is provided about each currently attached object dispatcher:
Region The number identifying the installation in which the object dispatcher is located.
Disp The object dispatcher number.
Flags xyz There are three flags. If the first flag (x) is c, it indicates that the object dispatcher is connected to the remote dispatcher listed in the display.
If the first flag is ?, it indicates the cached state is out-of-date, and the state of the connection to the remote dispatcher is unknown. The state is updated only in certain circumstances. (See the Tivoli Management Framework Maintenance and Troubleshooting Guide for details.)
If the first flag is –, it indicates that the remote dispatcher is down.
odadmin
1–82 Version 3.7
The second flag (y) is always t. The t flag indicates that the object dispatcher is trusted.
The third flag (z) is always –. The – flag indicates that the dispatcher is not a special dispatcher.
Port The listening port for the object dispatcher.
IPaddr The IP addresses of the client on which the object dispatcher is located.
Hostname(s) The host name and aliases of the client on which the object dispatcher is located.
The following suboptions are available with the odlist option:
list_od Lists members of the region.
add_ip_alias od ipaddr | hostname Adds an IP address alias for an object dispatcher. The request fails if the new IP address and object dispatcher port number match another object dispatcher IP address and port number. This suboption must be invoked from the TMR server.
delete_ip_alias od ipaddr Deletes an IP address alias for an object dispatcher. This suboption must be invoked from the TMR server.
add_hostname_alias od ipaddr hostname Adds a host name alias to an IP address associated with an object dispatcher. This suboption must be invoked from the TMR server.
odadmin
Tivoli Management Framework Reference Manual 1–83
Com
mands
delete_hostname_alias od ipaddr hostname Deletes a host name alias for an IP address associated with an object dispatcher. This suboption must be invoked from the TMR server.
change_ip od ipaddr [TRUE | FALSE] Changes the primary IP address associated with an object dispatcher. The request fails if the new IP address and object dispatcher port number match another object dispatcher IP address and port number. This suboption must be invoked from the TMR server.
rm_od od Removes an object dispatcher from the installation. The specified object dispatcher must be shut down before it is removed. A list of object IDs for objects that the dispatcher owned is displayed. The objects are removed, but references to the objects remain. This suboption must be invoked from the TMR server.
The rm_od option should only be run at the direction of Customer Support when a client installation has failed and it is impossible to recover. The normal method of deleting a client is with the wrmnode command.
set_kerberos_instance od kerberosname Changes the instance name of the Kerberos service used by the TMR server. The od option is always 1.
objects od Displays a list of the object IDs of objects owned by the object dispatcher.
odadmin
1–84 Version 3.7
reexec [od… | clients | all] Reexecutes the local object dispatcher. You can reexecute specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). The TMR server’s object dispatcher cannot be reexecuted from another system. You must have the super or senior role to run this option.
region [suboption] Provides remote region operations. You must have the super or senior role to run this option. The following suboptions are available for odadmin region. These suboptions should only be run at the direction of Customer Support to resolve low-level problems that cannot be handled from the Tivoli desktop or by the interregion CLI commands.
add_alias region ipaddr [name…] Adds a host name or IP alias for a remote region TMR server.
add_group_map region remotegroup localgroup Adds an object group map between regions.
add_group_id_map region remotename localname Adds mapping from user group names in the remote region to group names in the local region.
add_region region host port [crypt] Integrates an additional region. The password is read from standard input. You are prompted for the password if you run this command from a TTY.
add_role_map region remotegroup remoterole localrole
Adds a role map within a group map.
odadmin
Tivoli Management Framework Reference Manual 1–85
Com
mands
add_user_id_map region remotename localname Adds mapping from user login names in the remote region to login names in the local region.
change_region region host port [crypt] Changes configuration information for a remote region. The password is read from standard input. You are prompted for the password if you run this command from a teletype (TTY). An empty password indicates that the password should not be changed.
delete_alias region ipaddr [name…] Deletes a host name or IP alias for a remote region TMR server.
delete_group_map region remotegroup Deletes an object group map between regions.
delete_group_id_map region remotename Deletes user-group name mapping.
delete_region region Disconnects a remote region.
delete_role_map region remotegroup remoterole Deletes a role map within a group map.
delete_user_id_map region remotename Deletes login name mapping.
list_group_id_map region Displays mapping from user group names in the remote region to group names in the local region.
list_map region Lists object group and role maps between regions.
odadmin
1–86 Version 3.7
list_region [region] Lists connected regions. If the region option is not specified, lists regions that are connected to the local region.
list_user_id_map region Displays mapping from user login names in the remote region to login names in the local region.
set_region_crypt_level crypt Sets encryption level used by other TMR servers to connect to this region. The crypt option can be one of none, simple, or DES.
set_region_pw Sets encryption password for other TMR servers to connect to this region. The old password and the new password are read from standard input. You are prompted for the old and new passwords if you run this command from a TTY.
set_allow_rconnect {TRUE | FALSE} Allows the Tivoli Desktop for Windows to connect to a TMR server or client.
set_crypt_level {none | simple | DES} Sets encryption level for communication between object dispatchers within the local region. Normally, you need to use the following procedure to set the encryption level:
1. Enter odadmin shutdown clients.
2. Enter odadmin set_crypt_level crypt
where crypt specifies the encryption level and can be none, simple, or DES.
3. Enter odadmin start clients.
odadmin
Tivoli Management Framework Reference Manual 1–87
Com
mands
You must have the super or senior role to run the set_crypt_level option.
set_force_bind TRUE | FALSE {od… | clients | all} Forces Tivoli communication connections to bind to a single IP address. This option is used in certain high availability or failover configurations where multiple object dispatchers reside at different IP addresses on a single physical system.
set_install_pw Sets the installation password for future client installations. The old password and the new password are read from standard input. You are prompted for the old and new passwords if you run this command from a TTY. You must have the super or senior role to run this option.
set_iom_by_name TRUE | FALSE {od… | clients | all} Enables or disables Tivoli client communications to rely on the host name rather than the IP address of a TMR server when interpreting an IOM key and making a connection. Use this option for multihomed servers that are known by different IP addresses on different subnets.
set_keep_alive {on | off | poll | nopoll | time…} Sets options for checking for hosts that are down. You must have the super or senior role to run this option. The suboptions are as follows:
on | off Specifies whether to trust cached down-host information (on) or to try the host each time (off).
poll | nopoll Specifies whether to poll dispatchers (poll) or collect information implicitly (nopoll). The polling algorithm minimizes network traffic.
time Specifies the minimum poll interval time in seconds. Most dispatchers are not polled every interval.
odadmin
1–88 Version 3.7
The current keep_alive options can be read by running odadmin odinfo 1.
set_ORB_pw od Sets the password for communication between a TMR server’s object dispatcher and the specified client’s object dispatcher. The password is read from standard input. You are prompted for the password if you run this command from a TTY. You must have the super or senior role; you must also have root privileges on the TMR server and the specified object dispatcher.
Normally, when a client is added to the TMR server, the password used by the Tivoli client to communicate with the TMR server is set by the TMR server. This password is never stored in a file or transmitted over the network in plain text. However, there is a slight possibility that an intruder could get a copy of this password in its obscured form and decode it if your network is compromised during the installation process or if your database is compromised at a later date.
To change a client’s Tivoli password, do the following:
1. Shut down the affected client.
2. Run odadmin set_ORB_pw od on the TMR server.
3. Copy the file hostname-od-odb.adj from the Tivoli database directory to a file named odb.adj in the client database directory. Use a secure copying mechanism to copy this file. Set the file permissions on odb.adj to user-read/write, group-none, and other-none, and set the file ownership to root.
4. Restart the client’s object dispatcher.
odadmin
Tivoli Management Framework Reference Manual 1–89
Com
mands
set_port_range [range] Restricts the IOM channel communication ports and Tivoli communication between managed nodes to the specified port range. This option is especially helpful for firewall administrators who need to regulate the availability of ports. The oserv and gateway default ports are not affected by this option. Port ranges must be greater than 1023. To set the port range to null, use the following syntax:
odadmin set_port_range ““
set_rpc_max_threads num_threads Sets the concurrent remote procedure call thread limit for the dispatcher or the number of concurrent objcall threads. The default is 250.
shutdown [od… | clients | all] Shuts down the local object dispatcher. You can shut down specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). You must have the super or senior role to run this option. You cannot shut down the TMR server from a remote system. This option is not available to NetWare clients. NetWare clients must be stopped with the oservend command.
start [od… | clients | all] Starts the local object dispatcher. You can start specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). You must have the super or senior role to run this option. This option is not available to NetWare clients. NetWare clients must be started with the oservrun command.
trace {objcalls | services | errors | off [od… | clients | all]} Starts or stops debug tracing. You can specify that object calls, services, or errors be traced, or you can turn off debug tracing. You can start or stop tracing for specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). If
odadmin
1–90 Version 3.7
you do not specify specific clients or the clients or all option, debug tracing is started or stopped on the local object dispatcher. The trace information is collected in the odtrace.log file in the database directory. You can use the wtrace command to view this trace information. You must have the super or senior role to run odadmin trace.
Tivoli recommends that you do not enable error tracing by default. Tracing all object calls and services will impact the performance of your dispatcher. Use tracing of all object calls and services only when diagnosing specific problems.
use_kerberos {TRUE | FALSE [od… | clients | all]} Enables or disables Kerberos authentication. You can enable or disable Kerberos authentication for specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). If you do not specify specific clients or the clients or all option, Kerberos authentication is enabled or disabled for the local object dispatcher. You must have the super or senior role to run this option.
set_platform_license licensekey Adds or changes a platform license key. You must have the super or senior role to run this option.
get_platform_license Gets the current platform license key. You must have the super or senior role to run this option.
set_prod_license application licensekey Adds or changes an application license key. You must have the super or senior role to run this option.
get_prod_license application Gets the current license key for a specified application. You must have the super or senior role to run this option.
odadmin
Tivoli Management Framework Reference Manual 1–91
Com
mands
EXAMPLES
1. The following example gets help on the shutdown option. The output is also shown.
odadmin help shutdownshutdown [od … |clients|all]Stop object dispatcher(s)
2. The following example flushes the database files for all dispatchers:
odadmin db_sync all
3. The following example specifies the port range for all managed nodes to use for Tivoli communications. Ports 60000 through 60100 are specified.
odadmin set_port_range 60000-60100
SEE ALSOodbls, odstat, oserv, wconnect, wdisconn, wlsconn, wrmnode, wtrace, wupdate
odbls
1–92 Version 3.7
odbls Lists the contents of an object database.
SYNOPSISodbls [–aIilmOs] [–k directory] [–M meth_name] [oid]
DESCRIPTIONThe odbls command lists the contents of an object database.
Authorization
You must have read permission on the database to use the odbls command. In addition, you must have the super role to use the –s argument.
Arguments
–a Displays the attributes in the object database.
–I Walks through the object database inheritance list.
–i Displays the inheritance trees in the object database. To use this argument, you must use the Tivoli Management Region (TMR) server’s database.
–k directory The directory that contains the object database to be listed. If this option is not specified, the database in the current directory is listed.
–l Displays a verbose listing of the requested information.
–M meth_name Searches through method headers and dumps entries for meth_name. To use this option, you must use the TMR server’s database.
–m Displays the method headers and dumps all entries. To use this argument, you must use the TMR server’s database.
–O Walks through the object database. This is the default.
odbls
Tivoli Management Framework Reference Manual 1–93
Com
mands
–s Forces the appropriate object dispatcher to update the database that is to be listed. This synchronization ensures that the odbls command reports the same data that the object dispatcher is using. If this option is not specified, no synchronization is performed before listing the object database contents.
oid Restricts the listing to the specified object.
EXAMPLESThe following example lists all objects in the object database. The output is also shown. odbls –k /var/spool/tivoli/myhost.db
<bootstrap>200003.0.0200003.1.0200003.1.1200003.1.10200003.1.100200003.1.101200003.1.102200003.1.103200003.1.104
…
SEE ALSOodadmin
odstat
1–94 Version 3.7
odstat Lists the status of current and recent object calls.
SYNOPSISodstat [?] [–acdhlsv] [–o baseoid] [–p port_no]
(UNIX only) odstat [?] [–acdhlsv] –k dbdir [pid]
DESCRIPTIONThe odstat command lists the status of current and recent object calls for the specified object dispatcher. This command can list object calls from a running dispatcher.
The first form of the odstat command collects the object dispatcher history by invoking a method. You can specify a remote object dispatcher if desired.
The second form of the odstat command collects information by sending a signal to the object dispatcher. The –k argument specifies the database directory; the object dispatcher dumps its information to a temporary file in this directory. The pid option specifies the object dispatcher to send a signal to. The second form of the odstat command is useful when communication is disrupted for some reason, but is more specific than the first form. The second form can only send signals to local processes, and because the object dispatcher is owned by Administrator or root, you can only run this form if you are logged in as Administrator or root.
The odstat command returns its output in a columnar format. The columns are as follows:
tid The thread ID. The Tivoli object dispatcher is a multithreaded daemon process. When you start an object call, two threads are generated, one for the object call itself and one for the method being invoked.
type The thread and method type. The thread type flags are as follows:
O Object call thread (attached to an object request).
odstat
Tivoli Management Framework Reference Manual 1–95
Com
mands
M Method thread (attached to a method). The object call occurred on a different system, but the object is located on this system.
O+ Object call and method threads are the same (object is local to caller).
The method type flags are as follows:
a Asynchronous object call
q Queueing method
o Per-object method
b One-way object call
h Helperless method
d Daemon method
ptid Parent thread ID. The thread ID of the object call whose method made the current object call. If this field is blank, the object call is external (the object call was not made from a running method). The number before the dash is the dispatcher number where the parent thread resides. The number after the dash is the thread ID in the parent’s object dispatcher.
State One of the following states of the object call thread:
init The thread has been initialized.
ali The thread is performing a Tivoli Management Region (TMR) server lookup on the TMR server’s database.
mwait The thread is waiting for the associated method thread to complete.
rwait The thread is waiting for the caller to collect the results of an asynchronous object call.
done The object call is complete.
coord The method is serving as a transaction coordinator.
odstat
1–96 Version 3.7
err An internal error terminated the thread.
The states of method threads are as follows:
init The thread has been initialized.
gmeth The thread is obtaining the method code from another dispatcher.
hdwt The thread is waiting for the daemon-method process (nonqueueing daemon) to be ready to accept another request.
run The method is running.
serv The thread is performing an object services call.
done The method is complete.
twait The method is waiting on transaction status to commit or abort.
StdO Number of bytes written to standard output by the method.
StdE Number of bytes written to standard error by the method. Most threads do not write to standard error.
Start The time the thread started.
Err The thread’s error status. If this field is blank, no error occurred. Otherwise, this field is one of the following methods also described in the Tivoli Management Framework Maintenance and Troubleshooting Guide.
e=n The method returned n as its exit code. Error codes 0–21 are reserved for system-defined errors. Application error codes start at 22.
s=n The method died due to signal n.
S=n The method died due to signal n and produced a core file.
odstat
Tivoli Management Framework Reference Manual 1–97
Com
mands
XXX An uppercase word indicates an error in the object dispatcher.
Method Text of the method invocation. The first value is the object ID of the object in whose context the method was invoked. This can take the form of three numbers separated by periods, or three numbers separated by periods followed immediately by a pound sign (#), the class name information, and another pound sign. For example, 2222222.1.65#TMF.SysAdmin::InstanceManager# might be a valid object ID. The next word is the name of the method itself. The following words are the arguments to the method. The odstat command shows only the first 80 characters of the method invocation. For Interface Definition Language (IDL) generated methods, the arguments are not visible using the odstat command; see the wtrace command.
The history line separates the list of running threads from the list of completed threads.
If an asterisk (*) is the first character on a line, it indicates that the method exited with a nonzero status code or that one or more bytes were picked up on standard error.
For more information on the output produced by the odstat command, see the Tivoli Management Framework Maintenance and Troubleshooting Guide.
Authorization
You must have the super, senior, admin, or user role to run this command. You must be Administrator or root to run the –k form of this command.
Arguments
? Displays help on the odstat command.
–a Lists all threads. By default, system threads are omitted.
–c Lists currently running threads.
–d Lists the active method-daemon processes.
odstat
1–98 Version 3.7
–h Lists thread history (terminated threads) only.
–k dbdir Returns information from the dispatcher that is using the database in the specified directory. You should specify the object dispatcher’s process ID (pid) if you specify the –k dbdir option. If you do not, the odstat command randomly picks the object for the dispatcher’s process ID.
Note: This argument is for UNIX only.
–l Returns a long listing.
–o baseoid Returns object dispatcher status from another system.
–p port_no Sets the port number.
–s Returns a short listing.
–v Specifies verbose mode. Lists the last object-services request that the method or thread made, that request’s return code, the process ID associated with the method, and the last method invoked in a daemon thread.
pid Specifies the process ID of the dispatcher. If you specify this option, you must also specify the –k argument.
If no options are specified, the odstat command’s default is odstat –c –h –l –o 0.0.0.
EXAMPLES
1. The following example shows the output of odstat with no arguments. Explanations of the output are included throughout the example.
odstat
The output shows the methods currently running.
n_active = 5 n_free = 195\tid type ptid State StdO StdE Start Err Method\83 O+bhdoq run 0 0 Sat16:00\
200003.1.163#TMF_Scheduler::scheduler# start
odstat
Tivoli Management Framework Reference Manual 1–99
Com
mands
In the previous section of odstat output method thread, ID 83 is a “one way” invocation that invoked a helperless, queueing, daemon, per-object method implementation. It is currently in a run state, and started at 16:00 on Saturday. The object ID is 200003.1.163#TMF_Scheduler::scheduler# (the local scheduler object), and the method name is start.
(… output deleted for brevity ...)\---- history ----\
855 O+ 1-854 done 11 0 Sun16:16 0.0.0\get_name_registry\
856 O+hdoq 1-854 done 106 0 Sun16:16 200003.1.26 \lookup\
857 O+hd 1-854 done 6 0 Sun16:16\200003.1.128#TMF_UI::ActiveDesktopList# add_entry
The history line indicates the beginning of methods that have already completed. Methods 855, 856, and 857 are cascaded methods; they were invoked by method 854 on this oserv. (This example uses dispatcher 1.) Method 855 produced 11 bytes of standard output, 856 produced 106 bytes, and 857 produced 6 bytes.
(… more output deleted ...)\
* 918 O+hdoq 1-917 done 488 0 Sun16:27 e=12 200003.1.26 \lookup
Method 918 produced an error. The asterisk in the first column indicates a possible abnormal condition. The e=12 indicates an exception occurred. The wtrace command can be used to determine more information about the exception.
950 O 1-949 done 0 0 Sun16:28 <batch-mgr>\add_backref_optimized951 O+hdq 1-949 done 117 0 Sun16:28 \200003.1.378#TMF_Install::ProductInfo# add_backref_optimi\
zed
Method thread 950 is a batch-object-call manager. It indicates that there were multiple invocations of the same method on multiple objects at the same time. Line 951 is one of the batched method invocations managed by 950.
odstat
1–100 Version 3.7
* 1029 O+ 1-1026 done 0 0 Sun17:06 UNAUTHORIZED\200003.0.0 \get_principal_roles Root_PI-sluggo
Method 1029 shows a method that ran and failed at the core services level, below the exception facility. In this case, odstat translates the error code to an error name, where possible. Because an exception did not occur, wtrace is not likely to produce additional information about the error code.
2. The following example queries the method history on a remote machine. First, use the name registry lookup command to translate the machine name to an object reference, and then call odstat with that object reference.
wlookup –r ManagedNode –a
pokey 200003.2.7#TMF_ManagedNode::Managed_Node#sluggo 200003.1.285#TMF_ManagedNode::Managed_Node#
odstat –o 200003.2.7#TMF_ManagedNode::Managed_Node#
SEE ALSOodadmin, tmstat, wtrace
oinstall
Tivoli Management Framework Reference Manual 1–101
Com
mands
oinstall Installs, updates, or removes the Tivoli object dispatcher service, or daemon, in the Windows NT Service Manager.
SYNOPSISoinstall –install path
oinstall –remove
oinstall –update {[+interactive | –interactive] [+auto | –auto] [path]}
DESCRIPTIONThe oinstall command is used to install the Tivoli object dispatcher, or oserv, service into the Service Manager. This command is also used to update the oserv service or to remove it from the Windows NT Service Manager. When you install Tivoli on a Windows NT system, oinstall runs automatically during the installation process.
If you want to change the configuration of the service, for example to move the oserv binaries to a new location, you must run oinstall –update. (For more information about changing the Tivoli installation on a Windows NT Tivoli Management Region [TMR] server, see the Tivoli Enterprise Installation Guide.)
Authorization
Log on as service privilege
Arguments
–install Installs the oserv service into the Windows NT Service Manager. The service is installed in noninteractive mode and manual restart mode.
–remove Removes an oserv service from the Windows NT Service Manager.
oinstall
1–102 Version 3.7
–update Updates the oserv service with one or more of the following arguments:
+interactive | –interactive Enables or disables the interactive mode between the oserv service and the Tivoli desktop. Unless you are doing Tivoli ADE (Application Development Environment) development, do not enable the interactive mode.
+auto | –auto Enables or disables the automatic restart during reboot. By default, automatic restart is disabled.
path Specifies the path to the oserv.exe file on a local, New Technology File System (NTFS). It is assumed that the libuthreads.dll is located in the same library.
Note: If the service is running when you issue the oinstall –update command, the service will be stopped and must be restarted for the changes to take effect.
EXAMPLES
1. The following example installs the oserv service in the Service Manager. The oserv.exe file and the libuthreads.dll are located in c:\Tivoli.
oinstall –install C:\Tivoli\oserv.exe
2. The following example updates the oserv service in the Service Manager. The location of the oserv.exe file and libuthreads.dll is changed to c:\Tivoli\bin and the automatic restart mode is enabled.
oinstall –update +auto C:\Tivoli\bin\oserv.exe
oserv
Tivoli Management Framework Reference Manual 1–103
Com
mands
oserv Provides operations to control and configure object dispatchers.
SYNOPSISoserv –k dbdir [–a TRUE | FALSE] [–b install_dir] [–B libpath][–c crypt] [–C crypt] [–d] [–K kerb_serv_inst] [–l logfile] [–m swapsize] [–N ali [–r region]] [–N by_addr | by_name] [–p local_port] [–R irkey] [–S] [–s install_key] [–t max_trace_size] [–v] [–z TRUE | FALSE]
oserv –k dbdir [–b install_dir] [–B libpath] [–d] [–h TMEhost] [–l logfile] [–m swapsize] [–p local_port] [–S][–t max_trace_size] [–v] [–z TRUE | FALSE]
oserv –b install_dir –k dbdir [–f TRUE | FALSE] –i –r region[–a TRUE | FALSE] [–B libpath] [–c crypt] [–C crypt] [–d] [–K kerb_serv_inst] [–l logfile] [–m swapsize] [–N by_addr | by_name | ali] [–p local_port] [–R irkey] [–S] [–s install_key] [–t max_trace_size] [–v] [–z TRUE | FALSE]
oserv –k dbdir [–f TRUE | FALSE] –i –h TMEhost –b install_dir [–B libpath] [–d] [–l logfile] [–m swapsize] [–p local_port] [–S][–s install_key] [–t max_trace_size] [–v] [–z TRUE | FALSE]
Windows NT only
net start oserv /–option…
In Windows NT, the oserv command can only be invoked from the Service Manager. From the command line, the oserv command must be preceded by net start.
All arguments must be preceded by a slash and a dash (/–) instead of the single dash (–) use in UNIX. Any letter arguments that require a value cannot have a space between the letter and the value (for example, net start oserv /–Nbyaddr).
In Windows NT, the –k argument is not required. If not specified, the location of the database directory is taken from the registry.
oserv
1–104 Version 3.7
DESCRIPTIONThe oserv command starts the Tivoli object dispatcher. The Tivoli object dispatcher has multiple functions. It maintains the Tivoli object database on each system that has Tivoli installed, it routes object calls to the proper systems and objects, and it arranges for the execution of methods that are invoked in the context of objects that reside on the local system.
The first form of the oserv command is used to restart the object dispatcher on a Tivoli Management Region (TMR) server.
The second form of the oserv command is used to restart the object dispatcher on a Tivoli client.
The third form of the oserv command is used to initialize the object dispatcher on a TMR server.
The fourth form of the oserv command is used to initialize the object dispatcher on a Tivoli client.
Use the third and fourth forms of the oserv command only when using the installation programs.
The object dispatcher saves its configuration arguments in its database so that it resumes with its previous settings when it is restarted. When restarting an object dispatcher, you normally specify the –k argument plus the arguments for any settings you want to change. You can change the object dispatcher settings without shutting down the object dispatcher by using the odadmin command.
Authorization
root
Arguments
–a TRUE | FALSE Sets the flag that controls client installations. Client installations can be allowed (TRUE) or prohibited (FALSE). This argument is only valid for the TMR server.
–b install_dir Specifies the path name of the method binaries installation directory. This argument is required if the –i parameter is specified.
oserv
Tivoli Management Framework Reference Manual 1–105
Com
mands
–B libpath Specifies the shared library search path. If the –i argument is specified and this argument is not specified, the library search path is read from the invoker’s environment.
–c crypt Specifies the intraregion encryption level. The crypt option can be des, simple, or none.
–C crypt Specifies the interregion encryption level. The crypt option can be des, simple, or none.
–d Does not detach the object dispatcher from the controlling terminal. This argument is used for running an object dispatcher in a debugger. Standard output is not mapped to /dev/null.
–f TRUE | FALSE Forces an object dispatcher to bind to a single socket for all Tivoli client connections. Use this option when multiple dispatchers are running on a machine that has multiple Internet Protocol (IP) addresses. This forces each dispatcher to use the same IP address each time it communicates with clients.
–h TMEhost Specifies the name of the new Tivoli installation’s TMR server. This argument is used when starting the object dispatcher on a Tivoli client.
–i Initializes the object dispatcher. This argument is used the first time the object dispatcher is started on a system. It is not recommended that you use the –i argument without assistance from Customer Support.
–I Indicates to the object dispatcher that the object dispatcher is being started by inetd. This argument is only specified in inetd configuration files; it should not be specified on the command line.
–k dbdir Specifies the path name of the object database directory.
–K kerb_serv_inst Sets the Kerberos service instance name. This argument can only be specified for the TMR server.
oserv
1–106 Version 3.7
–l logfile Specifies the file to be used for logging messages. If this argument is not specified, messages are logged to the oservlog file.
–m swapsize Specifies the size of the swap space allocated by mmap.
–N by_addr | by_name | ali Refetches IP addresses for odlist entries using gethostbyaddr (by_addr), gethostbyname (by_name), or by replacing the TMR server’s odlist entry with the name and address of this system (ali). Do not move your TMR server to a new system by using the ali argument without first getting instructions for this procedure from Customer Support.
–p local_port Specifies the port number to use for communication with other processes. The port number must be less than 1024. This argument overrides the port specification in the /etc/services file. If this argument is not specified, the default is the port specification in the /etc/services file.
–P ali_port Specifies the port number to use for communication with the TMR server. The port number must be less than 1024. This argument is required only if the –i argument is specified and the TMR server port is different than the local object dispatcher’s port. This argument is valid only for Tivoli clients.
Note: This option is meant for use in development and test environments only. It should not be used in a production environment.
–r region Sets the region number. This argument can be used only with the –i argument or the –N ali argument.
–R irkey Specifies the interregion encryption key. If the irkey option is not specified, the interregion encryption key is read from standard input. You cannot specify the –R argument if the –s argument is specified.
–S Suppresses the output of oserv errors to syslogd.
oserv
Tivoli Management Framework Reference Manual 1–107
Com
mands
–s install_key Specifies the installation key. If the install_key option is not specified, the installation key is read from standard input. You cannot specify the –s argument if the –R argument is specified.
–t max_trace_size Sets the maximum size of the odtrace.log file created for use by the wtrace command.
–v Causes the oserv to use vfork() to spawn subprocesses instead of fork() on UNIX platforms. Specifying this flag has no effect on Windows NT.
–z TRUE | FALSE Enables (TRUE) or disables (FALSE) Kerberos authentication.
EXAMPLES
1. The following example starts the oserv, using all current defaults:
oserv –k /var/spool/Tivoli/myhost.db
2. The following example changes the path to the binary and library directories. This is helpful if the mount point to these directories is changed.
oserv –b /mnt/local/Tivoli/bin –B \/mnt/local/Tivoli/lib:/usr/lib \–k /var/spool/Tivoli/myhost.db
SEE ALSOodstat, odadmin, idlcall, objcall, oinstall, wsettap, wtrace
tivoli
1–108 Version 3.7
tivoli Starts the Tivoli graphical user interface and previews a new dialog.
SYNOPSIStivoli [–debug] [–display display] [–help] [–host host_name] [X_arguments] [–user user_name] [–port port_number] [–preview file.d var_name var_value …]
DESCRIPTIONThe tivoli command performs one of two different kinds of functions, depending on the options used. First, it can start the Tivoli graphical desktop for a Tivoli administrator. Second, it can preview a dialog created with dsl.
The –display option specifies the X-windows display on which to display the desktop or preview the dialog. If this option is omitted, the tivoli command defaults to the value defined in the DISPLAY environment variable. See the Tivoli Enterprise Installation Guide for more information on X-window resources.
The value of the X_arguments option are strings to be interpreted as X resource settings, for example, –background blue sets the default background color of all dialog backgrounds to blue.
If the –preview switch is omitted, the tivoli command starts the administrator’s desktop.
The –display and X_arguments options are not used for Windows NT.
For Tivoli Application Development Environment (ADE) developers, if the –preview option is specified, it instructs the User Interface (UI) server to preview the dialog contained in file.d. If the dialog contains dialog variables, the name and value of each dialog variable must follow the dialog file name. For example, if the dialog has two dialog variables named var1 and var2, the command must be invoked in the following way: tivoli –preview file.d var1 value-of-var-1 var2 value-of-var-2
If the value contains blanks, it needs to be enclosed in double quotation marks and single quotation marks, for example: tivoli –preview file.d var1 "'value of var 1'"
tivoli
Tivoli Management Framework Reference Manual 1–109
Com
mands
Authorization
user, admin, senior, super
Arguments
–debug Displays an additional dialog that contains debugging information for ADE developers.
–display display Specifies to display the desktop on the screen of the host specified in display.
–help Prints a usage message.
X_arguments Specifies the X resources to set for this session.
–host hostname Specifies the Tivoli managed node, including the TMR server where the Tivoli desktop should connect.
–port port_number Specifies the port number used by the object dispatcher.
–preview Instructs the UI server to preview the file specified by file.d. This argument can be used by Tivoli ADE developers to preview new dialogs before they are built into a product.
file.d Specifies the name of a .d file for Tivoli ADE developers.
var_name Specifies a Dialog Specification Language (DSL) variable name.
var_value Specifies the value associated with var_name.
–user username Specifies the login name to the managed node.
tmcmd
1–110 Version 3.7
tmcmd Forces a change of state of a running transaction.
SYNOPSIStmcmd [–p port] command transid…
DESCRIPTIONThe tmcmd command forces a transition of a transaction state. This command sends a message to the local transaction manager to force transactions into the state specified by the command option. The command option can specify one of abort, commit, prepare, complete, prepared, or completed.
The tmcmd command is primarily useful when testing and debugging the transaction manager, which is linked inside the oserv service, or daemon. Customer Support may ask you to run this command to recover from a severe or unusual problem as a last resort. It is strongly recommended that this command only be run with the direction and assistance of Customer Support, as this command can crash your oserv daemon or corrupt your database if used inappropriately.
Authorization
senior, super
Arguments
–p port Specifies the local port number.
command Specifies the state to force the transactions to. This argument can be one of abort, commit, prepare, complete, prepared, or completed.
transid Specifies the ID of the transaction for which a state change is to be forced. You can specify more than one transaction ID.
Diagnostics
If the command sent to the transaction manager violates the two-phase commit protocol, the oserv daemon may abort or your database could be corrupted.
tmcmd
Tivoli Management Framework Reference Manual 1–111
Com
mands
SEE ALSOodstat, tmstat
tmstat
1–112 Version 3.7
tmstat Displays the status of current transactions and locks.
SYNOPSIStmstat [–k dbdir] [–p port] [–r region] [–va] [baseobjid…]
DESCRIPTIONThis command displays the currently running transactions and locks and their current state. This command is primarily a debugging tool for users who are developing transaction-based applications; it allows such users to observe their transaction hierarchy.
Each transaction ID that is displayed implicitly contains the transaction hierarchy; you can interpret {transA}{transB} to be a child of {transA}.
Authorization
user, admin, senior, super
Arguments
–k dbdir Specifies the database directory.
–p port Specifies the local port number.
–r region Queries a different region. The region option specifies the base object ID on the remote region Tivoli Management Region (TMR) server.
–v Specifies verbose mode. Lists of subtransactions are dumped.
–a Displays all object IDs in the base list of the local region or the region specified by –r region.
baseobjid… Specifies the object dispatcher to query. Multiple baseobjid options can be specified.
tmstat
Tivoli Management Framework Reference Manual 1–113
Com
mands
EXAMPLESThe following example shows the output of tmstat with no arguments. An explanation of the output follows the example. tmstat
Transactions for 0.0.0Trid Type State Resources Polling Coord Parent MTid
----------------------------------------------------------{202020:1,202020:1,2:3}
Top-T running Yes No running running 40{202020:1,202020:1,2:3},{202020:1,202020:1,2:4}
Sub-T commit Yes Yes running running 44{202020:1,202020:1,2:3},{202020:1,202020:1,2:5}
Sub-T commit Yes Yes running running 45{202020:1,202020:1,2:3},{202020:1,202020:1,2:6}
Sub-T commit Yes Yes running running 46{202020:1,202020:1,2:3},{202020:1,202020:1,2:7}
Sub-T commit Yes Yes running running 47----------------------------------------------------------Cannot truncate log file:
Undo information pendingRedo information pendingTransaction event callback information pending
The output of tmstat consists of four sections: a table listing the current transactions, a section listing coordinators, a section stating why the transactionlog file cannot be deleted, and a section listing the remote transactions with local resources.
The previous example shows only two of the four possible sections. The table lists the transaction IDs of all local transactions, the transaction type, the transaction state, whether the transaction holds resources, whether the transaction is polling its parent or coordinator, and the state the transaction believes its parent or coordinator to be in. The MTid entry can be used to match up a transaction ID with a method thread ID in odstat.
The second section, listing coordinators, was empty and was skipped.
The third section indicates any current reasons why the transaction log file cannot be deleted. If this section is empty, the odadmin db_sync command may be used to truncate the log file immediately.
The fourth section, listing remote transactions with local resources, was empty and was skipped.
tmstat
1–114 Version 3.7
SEE ALSOodstat, tmcmd
w4inslcf.pl
Tivoli Management Framework Reference Manual 1–115
Com
mands
w4inslcf.pl Installs an endpoint on an AS/400 system.
SYNOPSISw4inslcf.pl [-v} [–a] [–F] [–I] [–g gwlabel[+port]] [–l ep_port] [–L config_args] [–N code] [–P] [–s dir_name] [–Y] {endpoint | –f filename}
INSTALLATION VARIABLES
–a Specifies asynchronous installation of endpoints. By default, the command waits for the endpoint to log in to its gateway before installing the next endpoint.
–F Forces an overwrite of an existing installation.
–I Indicates that the endpoint should be installed but not started.
–f filename Specifies the file containing a list of systems on which to install endpoints. This file contains one system name per line, specifying the user ID and password to be used. Each line in this file must be in the following format:
host [userID [password]]
–g gwlabel[+port] Specifies the IP address or host name and optionally the port number of the gateway to which the endpoint will log in.
–l ep_port Specifies the port number for the endpoint. The default port number is 9495.
–L config_args Passes configuration arguments to the daemon for starting the endpoint. To pass multiple arguments, enclose them in quotes. Refer to the lcfd command for a list of valid arguments.
w4inslcf.pl
1–116 Version 3.7
–N code Specifies additional languages to support by AS/400 code. The following are the codes: 2980 (Brazilian, Portuguese), 2989 (Chinese, simplified), 2924 (English uppercase and lowercase), 2938 (English uppercase), 2928 (French), 2929 (German), 2932 (Italian), 2962 (Japanese), 2986 (Korean), and 2931 (Spanish). To specify multiple languages, enclose them in quotes. The defaults are 2924 and 2938.
–P Specifies to prompt the user for a password. This argument overrides existing entries in a $HOME/.netrc file used for automatic logins.
–s dir_name Specifies the directory that contains the endpoint installation image. This directory can be on a compact disc, the TMR server, a gateway, or a network drive.
–Y Specifies that the installation should proceed without confirmation. The default is to request confirmation.
–v Writes verbose messages to standard output. Error messages are still written to standard error.
endpoint … Specifies the names or IP addresses of AS/400 systems on which the endpoints will be installed.
DESCRIPTIONThe w4inslcf command installs and optionally starts an AS/400 endpoint daemon job on one or more AS/400 systems. You can install multiple endpoints by listing the system name on the command line or supplying a file containing the system names. The file must contain one system name per line.
The command checks for prerequisites, sends code to the endpoint to be installed, using FTP, and then restores the product, 1TMELCF, to the AS/400, using RSTLICPGM. If requested, the endpoint is also started by issuing the AS/400 CL command STRTMEEPT.
w4inslcf.pl
Tivoli Management Framework Reference Manual 1–117
Com
mands
AUTHORYou must have root access to install endpoints but you do not need any Tivoli authorization roles. On the AS/400 you will need authority to use the RSTOBJ and RSTLICPGM commands and *SAVSYS special authority.
RETURNSThis command returns the following codes to standard output:
0 Indicates successful completion.
-1 Indicates failure due to an error.
Note: Host names for failed installations are written to os4LcfH.err and can be retried with the command using the –f os4LcfH.err keyword specified on the command.
EXAMPLES
1. The following example installs the AS/400 endpoint on the AS/400 systems as41.tivoli.com and as42.tivoli.com, connects to gateway smithers.tivoli.com using port 9494. The installation image is located in the /cdrom/1tmelcf directory.
w4inslcf.pl -v -g smithers.tivoli.com+9494 as41.tivoli.com as42.tivoli.com -s /cdrom/1tmelcf
2. The following example installs the AS/400 endpoint on the AS/400 system as42.tivoli.com, connects to gateway smithers.tivoli.com using port 9494, and installing French and German language support.
w4inslcf.pl -v -g smithers.tivoli.com+9494 -N ’2928 2929’ as42,tivoli.com
waddicon
1–118 Version 3.7
waddiconAdds an icon to a Windows Program Manager Group. (Windows 95, and Windows NT only.)
SYNOPSISwaddicon –g group_name [–c “command_line”] [–i icon_file] [–t icon_title] [–r] [–m “message”] [–a]
DESCRIPTIONThe waddicon command adds a new icon to a Windows 95, or Windows NT Program Manager group. If the group does not exist, it is created. If waddicon is launched as a batch from the Windows NT service agent, the created program group will be a common program group. If waddicon is launched from the Windows NT console agent, the created program group will be a user program group.
Arguments
–a Enables you to use this command asynchronously, such as in a batch file that is distributed to a PC where a user is not logged in. The command is actually executed when a user logs into the PC. You must use the command in a batch file if you specify this argument. This argument is supported on Windows NT only.
–c “command_line” Specifies the command line invoked by the icon.
–g group_name Specifies the program group name to which the icon is added.
–i icon_file Specifies the file containing the icon. If this argument is not specified, the Program Manager looks in the executable file specified by the –c argument.
–m “message” Specifies a message to be written to the WADDICON.ERR file if an error occurs when using this command with the –a argument. This argument is supported on Windows NT only.
waddicon
Tivoli Management Framework Reference Manual 1–119
Com
mands
–r Removes the specified icon. If no icon is specified, attempts to remove the entire program group.
–t icon_title Specifies the title (description) below the icon in the Program Manager.
RETURNSwaddicon returns one of the following:
0 Indicates the successful addition of the icon.
non-zero Indicates that waddicon was unsuccessful at adding the icon.
EXAMPLESThe following command example adds an icon called Word Processor for the word processor application to a Program Manager group called Applications:waddicon –g "Applications" –c \WP\WPROCESS.EXE \–t "Word Processor"
To remove the Word Processor icon from the Applications group, enter the following command:waddicon –g "Applications" –c \WP\WPROCESS.EXE \–t "Word Processor" –r
To remove the Applications group, enter the following command:waddicon –g "Applications" –r
To add an icon to a user’s desktop (on a Windows NT machine), include the following command in a batch file and distribute the file to the user’s PC. If an error occurs, the message following the –m argument is written to the WADDICON.ERR file.C:\TIVOLI|TMEAGENT|WIN32|CLI|WADDICON \–c "C:\FILES\MY_PROG.EXE" –t "My Program" \–m "Call #1 of waddicon" –a
waddpath
1–120 Version 3.7
waddpathAdds an entry to the path statement in the registry hive of the current control set. This command should be run from an endpoint. (Windows NT only)
SYNOPSISwaddpath path_value
DESCRIPTIONThe waddpath command adds an entry to Windows NT \SYSTEM\CurrentControlSet\Control\SessionManager\ Environment key path in the HKEY_LOCAL_MACHINE registry hive. After you add the entry, other applications will have a search path to the application.
This command returns a message indicating if it successfully completed or encountered an error.
Authorization
Administrator
Arguments
path_value Specifies the path entry to add to the registry hive in the current control set.
EXAMPLESTo add the \APPS\MISC\EXEC directory path to the registry hive, enter the following command:waddpath \APPS\MISC\EXEC
waddrealm
Tivoli Management Framework Reference Manual 1–121
Com
mands
waddrealmRegisters an HTTP/1.0 authentication realm with the HTTP daemon.
SYNOPSISwaddrealm –d RealmDir –p AuthProg –n RealmName
DESCRIPTIONThe waddrealm command adds an authentication realm to the HTTP daemon’s list of authentication realms. The waddrealm command is normally used only by an application during installation.
Authorization
senior, super
Arguments
–d RealmDir Specifies the realm directory. Specify this directory relative to the Hypertext Transfer Protocol (HTTP) base directory or the Common Gateway Interface (CGI) base directory.
–p AuthProg Specifies the authentication program name.
–n RealmName Specifies the realm name. Any name is permissible for RealmName.
EXAMPLESThe following example launches the authentication program MyProg when the /cgi-bin/MyDir realm is accessed:waddrealm –d /cgi–bin/MyDir –p \/cgi-bin/MyDir/MyProg –n RealmName
SEE ALSOwdelrealm, wlsrealms, wstarthttpd, wstophttpd
wadminep
1–122 Version 3.7
wadminepPerforms administrative operations on an endpoint.
SYNOPSISwadminep [–h] endpoint_name upgrade [upgrade_path]
DESCRIPTIONThe wadminep command is run from a managed node, but administers all supported endpoint platforms. Use wadminep to upgrade the endpoint daemon.
Authorization
The admin role is required with the privilege of root or Administrator on the endpoint.
Arguments
–h Displays a detailed usage statement listing all the commands available on wadminep.
endpoint_name Specifies the name of the endpoint on which the command will run.
upgrade [upgrade_path] Upgrades the endpoint software on the specified client. If a directory is not specified, the upgrade package is retrieved from $BINDIR/…/lcf_bundle on the gateway to which the endpoint is assigned.
EXAMPLESThe following example upgrades an existing endpoint to the newest release of the endpoint software. The upgrade package is located in /data/lcf_bundle.wadminep pine upgrade /data/lcf_bundle
SEE ALSOwinstlcf, lcfd
wauthadmin
Tivoli Management Framework Reference Manual 1–123
Com
mands
wauthadminAdds, removes, or displays the root authority of Tivoli administrators in a Tivoli Management Region (TMR).
SYNOPSISwauthadmin {–a administrator | –r administrator | –l [–v]}
DESCRIPTIONThe wauthadmin command serves two purposes in the management of Tivoli Administrator accounts:
■ Displays the names of all root administrators in a TMR.
■ Allows a root administrator to either grant root authorization to another administrator or revoke it.
When you install a TMR, the process creates an initial Tivoli administrator called the root administrator. This account possesses full, unrestricted privileges for accessing and managing systems. On UNIX platforms, the Tivoli root administrator account has UNIX root permissions; on Windows NT, the account has Administrator permissions. The wauthadmin command enables a root administrator to promote existing Tivoli administrators to root administrators. A TMR can have multiple root administrators.
The wauthadmin command also removes root authority from root administrator accounts. You must, however, retain at least one root administrator for each TMR.
With the –l argument, the wauthadmin command displays a list of Tivoli administrators who possess root authority in the local TMR.
Authorization
root administrator to grant or revoke root authority, user to display the list of root administrators.
Arguments
–a administrator Adds root authorization to the specified administrator.
wauthadmin
1–124 Version 3.7
–l Displays a list of administrators who have root authority in the TMR.
–r administrator Removes root authorization from the specified administrator.
–v Used only with the –l argument, provides more verbose information in the list.
EXAMPLES
1. The following example grants root authority to kimiko@ohio in the local TMR:
wauthadmin –a kimiko@ohio
2. The following example displays a verbose, detailed list of root administrators in the local TMR:
wauthadmin –lv
SEE ALSOwgetadmin, wsetadmin
wbkupdb
Tivoli Management Framework Reference Manual 1–125
Com
mands
wbkupdbBacks up and restores Tivoli databases.
SYNOPSISwbkupdb –e [nodename…]
wbkupdb –e –l [object nodename…]
wbkupdb [–d device] [–f] [–h nodename] [nodename…]
wbkupdb –l [–d device] [–f] [–h nodename] [object nodename…]
wbkupdb –d device –r [–R] [nodename…]
wbkupdb –d device –r –l [–R] [object nodename…]
wbkupdb –s
DESCRIPTIONThe wbkupdb command backs up and restores Tivoli databases. You can provide a list of managed node names as arguments to the wbkupdb command. If you do not specify any node arguments, the wbkupdb command backs up or restores every managed node in the TMR.
When the –e argument is used, this command estimates the total size of the backup archive. The wbkupdb command estimates the size of the backup of each managed node and the total size of the archive. This report is an estimate, but it is very close to the actual size of the backup image.
The third and fourth forms of this command (as shown in the synopsis) back up the database and store it in the specified file or device on the specified system. If the backup file already exists and is a disk file, you must specify the –f argument to overwrite the old backup file.
When the –r argument is used, this command restores Tivoli databases. This is primarily useful for reverting to a previously saved copy of the Tivoli database. The Tivoli Management Region (TMR) server or managed node that is to be restored must have Tivoli operational. If a restore operation is being performed from a system other than the TMR server, you cannot restore both the TMR server and the local database unless you specify the –R argument. If you restore the local database, you must use the explicit nodename syntax and specify the local node at the end or specify the –R argument.
wbkupdb
1–126 Version 3.7
If the object dispatcher that is to be restored is not running (and presumably cannot be run because its database is corrupted or missing), you can extract the database manually and put the files in the correct location in the database directory.
The wbkupdb command also saves any old versions of files and the notification database. Normally, these are not restored, because you probably do not want to read notices that have already been read. If for some reason the file is destroyed, you can restore it manually. The files_versions directory is not restored. If you want to see old revisions of system files, the files can be moved from the files_versions.restore directory as necessary.
Authorization
You must have the backup role in the TMR to create a backup, and the restore role in the TMR to perform a restore operation. The default backup directory requires root write access. Either log in as the root administrator or change the location of the backup file. If you are performing a “rescue” operation, you must be Administrator or root on the machine where the crashed database is located.
Arguments
–d device Specifies the file or device to which the backup file should be saved or from which the backup file should be retrieved. If you specify a file name with this argument, you can insert a file date and time anywhere in the file name by adding the variable %t. The variable is replaced with a date/time stamp in the form Mondd-hhmm. For example, if you specify –d /usr/backups/TMR1%t.bk, the resulting file will be named TMR1Dec21-0955.bk. The time is displayed in 24-hour mode.
–e Estimates the size of the backup.
–f Overwrites a previous backup file of the same name.
–h nodename Specifies the system that contains the tar file. The default is the TMR server.
wbkupdb
Tivoli Management Framework Reference Manual 1–127
Com
mands
–l Specifies that arguments on the command line are object/label pairs. This argument is for Tivoli internal use only.
–R Does not restart object dispatchers after restoring the database files. A number of files named *.restore are placed in the database directory. To effect the changes, use odadmin reexec or one of its derivatives to reexecute the dispatchers so that they pick up the restored copies of the databases.
–r Restores the databases for the specified nodes.
nodename Specifies the node to be backed up. You can specify multiple nodes.
object Specifies a backup object identifier.
-s Suppresses display of initial desktop message for each managed node being backed up.
EXAMPLES
1. The following example backs up the Tivoli databases for all managed nodes in the TMR from which the wbkupdb command was run. The backups are written to the user-defined file /usr/backups/TMR1.bk.
wbkupdb –d /usr/backups/TMR1.bk
2. The following example backs up the database of a single managed node, sherman. In this example, a destination directory and file name for the backup file are not specified. The backup is, therefore, written to the Tivoli database directory under a subdirectory called backups. The subdirectory is created if it did not exist when the wbkupdb command is run.
wbkupdb sherman
3. The following example restores a single managed node, sherman. The backup file used to restore the managed node is /usr/backups/TMR1.bk.
wbkupdb –r –d /usr/backups/TMR1.bk sherman
wbkupdb
1–128 Version 3.7
SEE ALSOwchkdb, winstall, wpatch, wserver, wclient
wbindmsg
Tivoli Management Framework Reference Manual 1–129
Com
mands
wbindmsgRetrieves a translated string from a local message catalog and binds any variables.
SYNOPSISwbindmsg catalog_name message_number default_string [arg…]
DESCRIPTIONThe wbindmsg command retrieves the message corresponding to message_number from the message catalog specified by catalog_name.
If the specified message cannot be retrieved from the specified message catalog in the current language environment, then the default_string is used. wbindmsg always looks for the specified message in set 2 of the specified message catalog.
The wbindmsg command uses the LANG and NLSPATH environment variables to find the message catalog appropriate for the current language environment. For example, if
LANG=fr_FR
and
NLSPATH=/tivoli/msg_cat/%L/%N.cat;\
/tivoli/msg_cat/%1%N.cat;\
/tivoli/msg_cat/C/%N.cat
wbindmsg will try the following path names to find the message catalog:
/tivoli/msg_cat/fr_FR/catalog_name.cat
/tivoli/msg_cat/fr/catalog_name.cat
/tivoli/msg_cat/C/catalog_name.cat
After the message is retrieved and bound, the resulting string is written to standard output.
Arguments
catalog_name Specifies the message catalog base name.
message_number Specifies the message number in the message catalog.
wbindmsg
1–130 Version 3.7
default_string Specifies the string to be used if the message cannot be retrieved from the message catalog.
[arg…] Specifies any optional arguments to be bound in place of the format directives in the message.
EXAMPLESThe following example retrieves the second message from the message catalog named my_catalog.cat. The default string is the same as the English version of the message, which contains two optional arguments jross and polyglot.wbindmsg my_catalog 2 \
"User %1\$s does not have an account on %2\$s" jross polyglot
This command produces the following output in English:
User jross does not have an account on polyglot.
wbroadcast
Tivoli Management Framework Reference Manual 1–131
Com
mands
wbroadcast Broadcasts a message to all Tivoli desktops.
SYNOPSISwbroadcast [optionaltext]
DESCRIPTIONThe wbroadcast command reads a message from standard input and broadcasts it to all desktops in the Tivoli environment. If the optionaltext option is used, this text, rather than standard input, is broadcast to all desktops in the Tivoli environment.
Authorization
admin, senior, super
Arguments
optionaltext Specifies the text to be broadcast.
EXAMPLESThe following example is of a typical message broadcast:wbroadcast << EOFRestoring Tivoli in 5 minutes. Please exit your desktops.EOF
wcatcher
1–132 Version 3.7
wcatcherSave custom dialogs before upgrading Tivoli Management Framework or a Tivoli application.
SYNOPSISwcatcher [–v] {–a | –r resource…} [–d parent_dir] [–s sub_dir]
DESCRIPTIONThe wcatcher command saves custom dialogs in Tivoli Management Framework or a Tivoli application before you upgrade to a new version of Tivoli Management Framework or the application. Examples of custom dialogs are those with added text fields or buttons.
For example, if you are preparing to upgrade to a new version of Tivoli User Administration, use this command to save your custom dialogs. After upgrading, use the wmrgaef command to reapply the custom dialogs to the new version.
The wcatcher command stores each custom dialog, and its corresponding original dialog, in a directory structure that you specify with the –d argument. The wcatcher command creates a directory called custom.sav (unless you specify a different name with the –s argument), and then searches each specified resource type to find custom dialogs. For each dialog, it saves the custom version and the original version in a subdirectory under custom.sav that has the same name as the resource. If a dialog has been customized on a per-instance basis, the dialogs are saved in a directory that has the name of the label instance.
Authorization
super
Arguments
–v Specifies verbose output.
–a Searches all registered resources for custom dialogs.
–r resource Searches a specific resource type. You can specify multiple resource types on a command line, but you must supply –r each time.
wcatcher
Tivoli Management Framework Reference Manual 1–133
Com
mands
–d parent_dir Specifies the path to the directory where each custom dialog and its corresponding original version is saved. If you do not supply a path, wcatcher writes the information about the customized dialog to the current working directory.
–s sub_dir Specifies the name of the directory. The default directory name is custom.sav.
EXAMPLESThe following command searches for all custom dialogs, writes the saved files to /tmp/aef, and names the directory my.dir.wcatcher –d /tmp/aef –s my.dir
SEE ALSO
wmrgaef
wcd
1–134 Version 3.7
wcd Changes the current working collection.
SYNOPSISwcd [label]
DESCRIPTIONThe wcd command changes the current working collection object to the collection object specified by the given label path. Each administrator or user has a separate current working collection associated with each parent process ID. This command’s valid argument is a full or partial label path.
Authorization
user, admin, senior, super
Arguments
label Specifies the new working collection; the specified object must be a collection object or policy region. This option can be a full label path (starting at the / collection) or a partial label path (relative to the current working collection). If this option is omitted, this command changes the working collection to the home collection. Each administrator’s home collection is /Administrators/name, where name is the administrator’s Tivoli principal name.
EXAMPLESThe following example changes the current working collection to policy region ceridwen-region. wcd /Regions/ceridwen-region
SEE ALSOwls, wpwd
wchkdb
Tivoli Management Framework Reference Manual 1–135
Com
mands
wchkdb Verifies and repairs the Tivoli database.
SYNOPSISwchkdb [–o outfile] [–u] [–x] {–f infile | –i | object…}
DESCRIPTIONThe wchkdb command verifies and repairs problems in the Tivoli database. This command does not affect any system files; it only modifies resources within the Tivoli environment.
Without the –u argument, wchkdb only verifies the database and reports discrepancies to standard output or, optionally, to an output file if the –o argument is used. The output file can later be passed to wchkdb with the –u and –f arguments to correct the discrepancies.
The –f infile option reads input from an output file generated in a previous run of wchkdb. All objects in the infile are checked. The –i argument reads a list of objects from standard input. You can also specify a list of objects on the command line. If no input options or object references are provided, all objects in the database are checked.
The –x argument enables verification across Tivoli Management Region (TMR) boundaries. Without this option, only resources within the current TMR are verified and repaired.
Authorization
senior or super
Arguments
–f infile Reads the specified input file, which was created during a previous run of wchkdb, and checks only those objects listed in the file. Only objects that failed during the previous run are included in the file.
–i Reads a list of objects from standard input. The list consists of object IDs and/or object names, each separated by a space.
–o outfile Writes a binary version of the displayed output to the specified file name.
wchkdb
1–136 Version 3.7
–u Updates the database, fixing any discrepancies found in the Tivoli resource database.
–x Verifies and repairs object references across TMR boundaries.
object… Specifies an object ID or object name to be verified and repaired.
RETURNSwchkdb returns one of the following values:
0 Indicates that wchkdb started successfully.
nonzero Indicates that wchkdb did not start successfully, either because of a syntax error or because the oserv is not available.
EXAMPLES
1. The following example verifies and, if needed, repairs the Tivoli database. Object references are checked across TMR boundaries.
wchkdb –u –x
2. The following example verifies object references in the current TMR only. No changes are made to the Tivoli database. Problems are, however, displayed to standard output and written to a binary output file, /tmp/check.out.
wchkdb –o /tmp/check.out
3. The following example reads the results from a previous run of wchkdb (/tmp/check.out) and updates the Tivoli database as needed:
wchkdb –u –f /tmp/check.out
wchknode
Tivoli Management Framework Reference Manual 1–137
Com
mands
wchknode Verifies and updates references to a specific dispatcher number from parts of the Tivoli database.
SYNOPSISwchknode [–n –c –s –x –v –u dispatcher_num]
DESCRIPTIONThe wchknode command synchronizes the Tivoli Management Region (TMR) server database with the database of dispatcher_num. wchknode verifies the Tivoli name registry (–n), Tivoli collections (–c), or subscription lists (–s). If neither the –n, –c, nor –s arguments are specified, wchknode checks all of these objects. If the –u argument is specified, wchknode updates all references to dispatcher_num. Without this option, wchknode finds all references and prints discrepancies to the screen. If dispatcher_num is not specified, wchknode verifies the entire TMR.
The wchknode command is run from the TMR server. By default, the command runs only in the local TMR. Use the –x argument to verify references in connected TMRs.
When you do not have time to run a full wchkdb, run wchknode to check the references to a dispatcher number after a managed node or dispatcher’s database has been restored.
Authorization
senior or super in TMR
Arguments
–n Verifies references to dispatcher_num in the Tivoli name registry.
–c Verifies references to dispatcher_num in Tivoli collections.
–s Verifies references to dispatcher_num in subscription lists.
wchknode
1–138 Version 3.7
–x Verifies references to dispatcher_num across TMR boundaries.
–v Prints verbose messages to the screen.
–u Updates any discrepancies found during the verification. If this argument is not specified, wchknode prints all discrepancies to screen.
dispatcher_num Identifies the dispatcher number of the managed node that wchknode is to verify. To determine the correct dispatcher number, use the odadmin odlist command.
EXAMPLES
1. The following example verifies and updates all references to managed node yellow (dispatcher 7) in the Tivoli name registry, Tivoli collections, and subscription lists. wchknode will search the local TMR and all connected TMRs.
wchknode –x –u 7
2. The following example verifies the Tivoli name registry for references to managed node thor (dispatcher 5). References will not be removed, but printed to screen.
wchknode –n 5
SEE ALSOwchkdb, wrmnode
wchkpol
Tivoli Management Framework Reference Manual 1–139
Com
mands
wchkpol Verifies policy region members against policy.
SYNOPSISwchkpol [–c collection] [–f file] [–a] [–r resource] [–l label]… region
DESCRIPTIONThe wchkpol command verifies that all or a subset of a policy region’s members comply with the policy enabled for the region. For each member that does not pass the policy verification, a message is sent to standard output. The –f argument sends the output to a log file. With the –c argument, wchkpol can also create a collection of those members that did not pass the verification.
Authorization
admin, senior, super
Arguments
–c collection Creates a collection in which to put members that failed the policy verification.
–f file Creates a log file containing a list of members that failed the policy check.
–a Verifies all members of the policy region.
–r resource Verifies all policy region members that are of the resource type specified.
–l label Verifies the resource specified by label.
region Specifies the policy region whose members are to be verified.
EXAMPLES
1. The following example verifies the policy for all members of the policy region ceridwen-region.
wchkpol –a /Regions/ceridwen-region
wchkpol
1–140 Version 3.7
2. The following example verifies the policy for all managed nodes in the policy region ceridwen-region and creates a collection named failures to contain any managed nodes that do not pass the policy verification.
wchkpol –c failures –r ManagedNode ceridwen–region
SEE ALSOwcrtpr, wcrtpol, wdelpr, wgetdfpol, wgetpolm, wlspol, wlspolm, wputpolm
wci
Tivoli Management Framework Reference Manual 1–141
Com
mands
wci Checks in Revision Control System (RCS) revisions.
SYNOPSISwci [arguments] file …
DESCRIPTIONwci stores new revisions into RCS files. Each path name matching an RCS suffix is taken to be an RCS file. All others are assumed to be working files containing new revisions. wci deposits the contents of each working file into the corresponding RCS file. If only a working file is given, wci tries to find the corresponding RCS file in an RCS subdirectory and then in the working file’s directory. For more details, see the section “FILE NAMING,” which follows.
For wci to work, the caller’s login must be on the access list, unless the access list is empty or the caller is the super user or the owner of the file. To append a new revision to an existing branch, the tip revision on that branch must be locked by the caller. Otherwise, only a new branch can be created. This restriction is not enforced for the owner of the file if non-strict locking is used (see wrcs). A lock held by someone else may be broken with the wrcs command.
Unless the –f argument is given, wci checks whether the revision to be deposited differs from the preceding one. If not, instead of creating a new revision wci reverts to the preceding one. To revert, ordinary wci removes the working file and any lock; wci –l keeps and wci –u removes any lock, and then they both generate a new working file much as if wco –l or wco –u had been applied to the preceding revision. When reverting, any –n and –s arguments apply to the preceding revision.
For each revision deposited, wci prompts for a log message. The log message should summarize the change and must be terminated by end-of-file or by a line containing ‘.’ by itself. If several files are checked in, wci asks whether to reuse the previous log message. If the standard input is not a terminal, wci suppresses the prompt and uses the same log message for all files. See also –m.
wci
1–142 Version 3.7
If the RCS file does not exist, wci creates it and deposits the contents of the working file as the initial revision (default number: 1.1). The access list is initialized to empty. Instead of the log message, wci requests descriptive text (see –t).
The number rev of the deposited revision can be given by any of the arguments –f, –I, –k, –l, –M, –q, –r, or –u. rev may be symbolic, numeric, or mixed. If rev is $, wci determines the revision number from keyword values in the working file.
If rev is a revision number, it must be higher than the latest one on the branch to which rev belongs, or must start a new branch.
If rev is a branch rather than a revision number, the new revision is appended to that branch. The level number is obtained by incrementing the tip revision number of that branch. If rev indicates a nonexisting branch, that branch is created with the initial revision numbered rev.1.
If rev is omitted, wci tries to derive the new revision number from the caller’s last lock. If the caller has locked the tip revision of a branch, the new revision is appended to that branch. The new revision number is obtained by incrementing the tip revision number. If the caller locked a non-tip revision, a new branch is started at that revision by incrementing the highest branch number at that revision. The default initial branch and level numbers are 1.
If rev is omitted and the caller has no lock but owns the file and locking is not set to strict, the revision is appended to the default branch (normally the trunk; see the –b argument of wrcs).
Exception: On the trunk, revisions can be appended to the end, but not inserted.
An RCS file created by wci inherits the read and execute permissions from the working file. If the RCS file exists, wci preserves its read and execute permissions. wci always turns off all write permissions of RCS files.
Arguments
–r [rev] Checks in a revision, releases the corresponding lock, and removes the working file. This is the default.
wci
Tivoli Management Framework Reference Manual 1–143
Com
mands
The –r argument has an unusual meaning in wci. In other RCS commands, –r merely specifies a revision number, but in wci it also releases a lock and removes the working file. See –u for an example.
–l [rev] Works like –r, except it performs an additional wco –l for the deposited revision. Thus, the deposited revision is immediately checked out again and locked. This is useful for saving a revision although you want to continue editing it after the check-in.
–u [rev] Works like –l, except that the deposited revision is not locked. This lets you read the working file immediately after check-in.
The –l, –r, and –u arguments are mutually exclusive and silently override each other. For example, wci –u –r is equivalent to wci –r because –r overrides –u.
–f [rev] Forces a deposit; the new revision is deposited even if it is not different from the preceding one.
–k [rev] Searches the working file for keyword values to determine its revision number, creation date, state, and author (see wco), and assigns these values to the deposited revision, rather than computing them locally. It also generates a default login message noting the login of the caller and the actual check-in date. This argument is useful for software distribution. A revision that is sent to several sites should be checked in with the –k argument at these sites to preserve the original number, date, author, and state. The extracted keyword values and the default log message may be overridden with the arguments –d, –m, –s, –w, and any argument that carries a revision number.
–q [rev] Quiet mode; diagnostic output is not printed. A revision that is not different from the preceding one is not deposited, unless –f is given.
–I [rev] Interactive mode; the user is prompted and questioned even if the standard input is not a terminal.
wci
1–144 Version 3.7
–d “[date]” Uses date for the check-in date and time. The date is specified in free format as explained in wco. This is useful for specifying a check-in date other than the actual date, and for –k if no date is available. If date is empty, the working file’s time of last modification is used.
–M [rev] Sets the modification time on any new working file to be the date of the retrieved revision. For example, wci –d –M –u f does not alter f’s modification time, even if f’s contents change due to keyword substitution. Use this argument with care; it can confuse make.
–m msg Uses the string msg as the log message for all revisions checked in.
–n name Assigns the symbolic name name to the number of the checked-in revision. wci prints an error message if name is already assigned to another number.
–N name Same as –n, except that it overrides a previous assignment of name.
–s state Sets the state of the checked-in revision to the identifier state. The default state is Exp.
–t file Writes descriptive text from the contents of file into the RCS file, deleting the existing text. The file may not begin with –.
–t string Writes descriptive text from the string into the RCS file, deleting the existing text.
The –t argument, in both its forms, has effect only during an initial check-in; it is silently ignored otherwise.
During the initial check-in, if –t is not given, wci obtains the text from standard input, terminated by end-of-file or by a line containing ‘.’ by itself. The user is prompted for the text if interaction is possible; see –I.
For backward compatibility with older versions of RCS, –t without string is ignored.
wci
Tivoli Management Framework Reference Manual 1–145
Com
mands
–w login Uses login for the author field of the deposited revision. Useful for specifying an author other than the actual author, and for –k if no author is available.
–V n Emulates RCS version n. See wco for details.
–x suffixes Specifies the suffixes for RCS files. A nonempty suffix matches any path name ending in the suffix. An empty suffix matches any path name of the form RCS/file or path/RCS/file. The –x argument can specify a list of suffixes separated by /. For example, –x,v/a specifies two suffixes: ,v and the empty suffix. If two or more suffixes are specified, they are tried in order when looking for an RCS file; the first one that works is used for that file. If no RCS file is found but an RCS file can be created, the suffixes are tried in order to determine the new RCS file’s name. The default for suffixes is installation-dependent; normally it is ,v/ for hosts such as UNIX that permit commas in file names, and is empty (for example, just the empty suffix) for other hosts.
FILE NAMINGPairs of RCS files and working files may be specified in three ways (see also the example section):
1. Both the RCS file and the working file are given. The RCS path name is of the form path1/workfileX and the working path name is of the form path2/workfile where path1/ and path2/ are (possibly different or empty) paths, workfile is a file name, and Xa is an RCS suffix. If Xa is empty, path1/ must be RCS/ or must end in /RCS/.
2. Only the RCS file is given. Then the working file is created in the current directory and its name is derived from the name of the RCS file by removing Bpath1/ and the suffix X.
3. Only the working file is given. Then wci considers each RCS suffix X in turn, looking for an RCS file of the form path2/RCS/workfileXa or (if the former is not found and X is nonempty) path2/workfileX.
If the RCS file is specified without a path in methods 1 and 2, wci looks
wci
1–146 Version 3.7
for the RCS file first in the directory ./RCS and then in the current directory.
wci reports an error if an attempt to open an RCS file fails for an unusual reason, even if the RCS file’s path name is just one of several possibilities. For example, to suppress the use of RCS commands in directory d, create a regular file named d/RCS so that casual attempts to use RCS commands in d fail because d/RCS is not a directory.
EXAMPLES
1. Suppose ,v is an RCS suffix and the current directory contains a subdirectory RCS with an RCS file io.c,v. Then each of the following commands checks a copy of io.ca into RCS/io.c,v as the latest revision, removing io.c:
wci io.c; wci RCS/io.c,v; wci io.c,v;wci io.c RCS/io.c,v; wci io.c io.c,v;wci RCS/io.c,v io.c; wci io.c,v io.c;
2. Suppose instead that the empty suffix is an RCS suffix and the current directory contains a subdirectory RCS with an RCS file io.c. Each of the following commands checks in a new revision:
wci io.c; wci RCS/io.c;wci io.c RCS/io.c;wci RCS/io.c io.c;
SEE ALSOwco, wident, wrcs, wrcsdiff, wrcsmerge, wrlog; Walter F. Tichy, RCS—A System for Version Control, Software—Practice & Experience 15, 7 (July 1985), 637-654.
FILESSeveral temporary files may be created in the directory containing the working file, and also in the temporary directory (see TMPDIR in the section “ENVIRONMENT”). Semaphore files are created in the directory containing the RCS file. With a nonempty suffix, the semaphore names begin with the first character of the suffix; therefore, do not specify a suffix whose first character could be that of a working file name. With an empty suffix, the semaphore names end with _, so working file names should not end with _.
wci
Tivoli Management Framework Reference Manual 1–147
Com
mands
wci never changes an RCS or working file. Normally, wci unlinks the file and creates a new one; but instead of breaking a chain of one or more symbolic links to an RCS file, it unlinks the destination file instead. Therefore, wci breaks any hard or symbolic links to any working file it changes; and hard links to RCS files are ineffective, but symbolic links to RCS files are preserved.
The effective user must be able to search and write the directory containing the RCS file. Normally, the real user must be able to read the RCS and working files and to search and write the directory containing the working file; however, some older hosts cannot easily switch between real and effective users, so on these hosts the effective user is used for all accesses. The effective user is the same as the real user unless your copies of wci and wco have setuid privileges. As described in the next section, these privileges yield extra security if the effective user owns all RCS files and directories, and if only the effective user can write RCS directories.
Users can control access to RCS files by setting the permissions of the directory containing the files; only users with write access to the directory can use RCS commands to change its RCS files. For example, in hosts that allow a user to belong to several groups, one can make a group’s RCS directories writable to that group only. This approach suffices for informal projects, but it means that any group member can arbitrarily change the group’s RCS files, and can even remove them entirely. Hence more formal projects sometimes distinguish between an RCS administrator, who can change the RCS files at will, and other project members, who can check in new revisions but cannot otherwise change the RCS files.
SETUID USE on UNIX (UNIX Only)
To prevent anybody but their RCS administrator from deleting revisions, a set of users can employ setuid privileges as follows:
■ Check that the host supports RCS setuid use. Consult a trustworthy expert if there are any doubts. It is best if the setuid() system call works as described in Posix 1003.1a Draft 5, because RCS can switch back and forth easily between real and effective users, even if the real user is root. If not, the second best is if the setuid() system call supports saved setuid (the {_POSIX_SAVED_IDS}
wci
1–148 Version 3.7
behavior of Posix 1003.1-1990); this fails only if the real user is root. If RCS detects any failure in setuid, it quits immediately.
■ Choose a user A to serve as RCS administrator for the set of users. Only A will be able to invoke the wrcs command on the users’ RCS files. A should not be root or any other user with special powers. Mutually suspicious sets of users should use different administrators.
■ Choose a path name B that will be a directory of files to be executed by the users.
■ Have A set up B to contain copies of wci and wco that are setuid to A by copying the commands from their standard installation directory D as follows:
mkdir Bcp D/wc[io] Bchmod go–w,u+s B/wc[io]
■ Have each user prepend B to their path as follows:
PATH=B:$PATH; export PATH # ordinary shellset path=(B $path) # C shell
■ Have A create each RCS directory R with write access only to A as follows:
mkdir Rchmod go–w R
■ If you want to let only certain users read the RCS files, put the users into a group G, and have A further protect the RCS directory as follows:
chgrp G Rchmod g–w,o–rwx R
■ Have A copy old RCS files (if any) into R, to ensure that A owns them.
■ An RCS file’s access list limits who can check in and lock revisions. The default access list is empty, which grants check-in access to anyone who can read the RCS file. If you want to limit check-in access, have A invoke wrcs–aa on the file; see wrcs. In particular, wrcs–e–a A limits access to just A.
wci
Tivoli Management Framework Reference Manual 1–149
Com
mands
■ Have A initialize any new RCS files with wrcs–i before initial check-in, adding the –a argument if you want to limit check-in access.
■ Give setuid privileges only to wci and wco.
■ Do not use other setuid commands to invoke RCS commands.
ENVIRONMENT
RCSINIT Arguments attached to the argument list, separated by spaces. A backslash escapes spaces within an argument. The RCSINIT arguments are prepended to the argument lists of most RCS commands. Useful RCSINIT arguments include –q, –V, and –x.
TMPDIR Name of the temporary directory. If not set, the environment variables TMP and TEMP are inspected instead and the first value found is taken; if none of them are set, a host-dependent default is used, typically /tmp.
DIAGNOSTICSFor each revision, wci prints the RCS file, the working file, and the number of both the deposited and the preceding revision. The exit status is zero if and only if all operations were successful.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.9; Release Date: 1991/110/07. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991 by Paul Eggert.
wclient
1–150 Version 3.7
wclient Installs a Tivoli managed node.
SYNOPSISwclient –c source_dir [–d] [–I] [–P] [–t | –T traa] [–y] [–f filename] [–p policy_region] [–U user_acct] [install_variables] [managed_node ...]
DESCRIPTIONThe wclient command installs a Tivoli managed node from the command line when invoked on a managed node or the Tivoli Management Region (TMR) server.
Authorization
install_client or super
Arguments
–c source_dir Specifies the complete path to the installation image.
–d Sets install_variables to the last set values. Commonly, each installed managed node uses the same set of installation directories, and this argument provides a shortcut for setting the variables.
–I Causes wclient to prompt for the installation password. If you do not use this argument, there will not be a password prompt.
–P Causes wclient to prompt for the root password for the machine. If you specify more than one machine, wclient assumes they all have the same root password.
–t Specifies that the account and password specified with the –U account should be used as the Tivoli Remote Access Account (TRAA).
–y Specifies that the installation should proceed without confirmation. By default, wclient identifies the actions that must be taken to perform the installation and requests confirmation before continuing. Using this
wclient
Tivoli Management Framework Reference Manual 1–151
Com
mands
argument, wclient identifies the actions and performs the installation without requesting the confirmation.
–f filename Specifies a text file containing a list of machines to be installed. The file contains one line per machine with the format hostname,user,password. user is optional. If not specified, the default is root or Administrator. There can be no spaces between entries. The content of each line determines the default method.
■ For the default, each entry contains only the machine name.
■ For account access, each entry contains the machine name followed by a comma (,), the userid followed by a comma (,), and then the password.
Note: Passwords are not encrypted. Anyone with access to this file can see the passwords.
■ For trusted host access, each entry contains the machine name followed by a comma (,).
The following is an example of a machine file:
elmoak,chris,&rewscedar,,sesame liveoak,
–p policy_region Specifies the name of the policy region in which the Tivoli managed nodes will be installed.
–T traa Specifies the account name to be used for the TRAA. When you use this argument, you will be prompted for the password.
–U user_acct Specifies an account and password other than root for installing each managed node. When you use this argument, you will be prompted for the password.
wclient
1–152 Version 3.7
install_variables Indicates keyword=value pairs that control the installation. These variables can be set or defaulted on the command line. These variables specify required information or override default information.
Several of the installation variables specify the directories where the Tivoli managed node will be installed. If a directory contains files from a previous installation, wclient does not reinstall the files. However, you can force any of these directories to be reinstalled by entering a ! character as the value for the variable.
The following are the installation variables related to the installation directories:
BIN=binaries Overrides the default installation path (/usr/local/Tivoli/bin) for the Tivoli Management Framework binaries.
LIB=libraries Overrides the default installation path (/usr/local/Tivoli/lib) for the Tivoli Management Framework libraries.
DB=client_database Overrides the default installation path (/var/spool/Tivoli) for the Tivoli Management Framework client database.
MAN=manpage Overrides the default installation path (/usr/local/Tivoli/man) for the Tivoli Management Framework man pages.
APPD=X11_defaults Overrides the default installation path (/usr/lib/X11/app-defaults) for the X11 application defaults.
wclient
Tivoli Management Framework Reference Manual 1–153
Com
mands
CAT=message_catalog Overrides the default installation path (/usr/local/Tivoli/msg_cat) for the Tivoli Management Framework message catalogs.
The following are other useful installation variables:
@AutoStart@=0 | 1 Indicates whether the Tivoli daemon should be started (1) at system boot time. By default, the daemon is not started (0).
@SetPort@=0 | 1 Indicates whether to configure (1) or not configure (0) the remote start capability of the Tivoli daemon. Enabling remote start requires changes to /etc/inetd.conf and /etc/services. By default, this capability is configured.
@CreatePaths@=0 | 1 Indicates whether to create (1) the specified directories if they do not already exist. By default, directories are not created (0). It is considered an error if a directory you specified with an install_variables does not exist.
@ClientAddNoTrans@=yes | no Indicates whether managed nodes should be added using a transaction. Adding managed nodes without a transaction can save significant time when installing over slow links. If an error occurs, however, you should be sure to run wchkdb to verify the state of the database.
@ForceBind@=yes | no Indicates whether Tivoli communication connections are forced to bind to a single Internet Protocol (IP) address. This option is used in certain high-availability or failover configurations where multiple object dispatchers reside at different IP addresses on a single physical system.
wclient
1–154 Version 3.7
managed_node… Specifies the machines where a Tivoli managed node will be installed. This option is not required if the –f argument is used.
EXAMPLES
1. The following example installs managed nodes dan and barney in policy region bedrock in the default locations. The user will be prompted for the installation password and the root password for these managed nodes. The complete path to the installation image is /cdrom. The example also overrides the default location for the client database directory and installs this database in /var/spool/database instead.
wclient –dIP –c /cdrom –p bedrock DB=/var/spool/databasedan barney
2. The following example installs managed nodes cook and everest in policy region austin: /
wclient –d –c /cdrom –p austin cook everest
FILES
UNIX Files
/tmp/tivoli.cinstall This file resides on the TMR server and contains verbose debugging information from all managed node and product installation attempts.
/tmp/install2.cfg.error /tmp/install2.cfg.output This transient file is created on a managed node during the initialization of its Tivoli database. After a successful initialization, these files are removed.
/tmp/client.cfg.error /tmp/client.cfg.output This transient file is created on a managed node during the configuration of its Tivoli database. After a successful initialization, these files are removed.
wclient
Tivoli Management Framework Reference Manual 1–155
Com
mands
/etc/Tivoli/setup_env.sh This file contains useful Bourne shell environment variables. The file can be dotted from Bourne shell compatible shells after installation.
/etc/Tivoli/setup_env.csh This file contains useful C shell environment variables. The file can be dotted from C shell compatible shells after installation.
Windows NT Files
\%TMPDIR\tivoli.cinstall This file resides on the TMR server and contains verbose debugging information from all managed node and product installation attempts.
\%TMPDIR\install2.cfg.error \tmp\install2.cfg.output This transient file is created on a managed node during the initialization of its Tivoli database. After a successful initialization, these files are removed.
\%TMPDIR\client.cfg.error \tmp\client.cfg.output This transient file is created on a managed node during the configuration of its Tivoli database. After a successful initialization, these files are removed.
SEE ALSOwserver, winstall, wchkdb
wclrblk
1–156 Version 3.7
wclrblkRemoves a block of statements from a file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwclrblk [–r] –s “start_string” –e “end_string” [–o output_file] filename
DESCRIPTIONThe wclrblk command removes a block of statements from a file. This command is intended to remove a block of statements clearly delimited at the beginning and end of the block (such as a block added using winsblk or wrplblk). The caller must insert the delimiting lines along with the actual block of statements.
Arguments
–e “end_string” Specifies a string to search for that signifies the end of the block of statements in the file. You must surround the string with double quotation marks.
–o output_file Specifies the name of the file that will receive the processed file. If this parameter is not specified, output is written to standard output. You cannot redirect the processed file to the file that you are modifying.
–r Removes the delimiter lines in addition to the block of statements.
–s “start_string” Specifies a string to search for that signifies the start of the block of statements in the file. You must surround the string with double quotation marks.
filename Specifies the file from which the block should be removed.
wclrblk
Tivoli Management Framework Reference Manual 1–157
Com
mands
RETURNSwclrblk returns one of the following:
0 Indicates that wclrblk successfully removed the specified block of statements.
nonzero Indicates that wclrblk did not successfully remove the specified block of statements.
EXAMPLESTo remove delimiter lines and the block of statements starting with [keyboard] and ending with type=4 from the SYSTEM.INI file, enter the following command:wclrblk –r –s "[keyboard]" –e "type=4" \–o C:\TEMP\OUTPUT.FIL C:\WINDOWS\SYSTEM.INI
The output is written to the OUTPUT.FIL file, as specified by the –o argument.
SEE ALSOwinsblk, wrplblk
wclrline
1–158 Version 3.7
wclrlineRemoves a single line from a file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwclrline [–f] –s “search_string” [–o output_file] filename
DESCRIPTIONThe wclrline command removes a line from a text file, as specified by the search string. By default, output from this command is written to standard output.
Arguments
–f Processes only the first occurrence of the search string. If this argument is not specified, all lines containing the search string are removed.
–o output_file Specifies the name of the file that will receive the processed file. If this parameter is not specified, output is written to standard output.
–s “search_string” Specifies a string to search for in the file. If the search string is contained in a line, the line is removed from the file. You must surround the string with double quotation marks.
filename Specifies the name of the file from which to read.
RETURNSwclrline returns one of the following:
0 Indicates that wclrline successfully removed the specified line.
nonzero Indicates that wclrline did not successfully remove the specified line.
wclrline
Tivoli Management Framework Reference Manual 1–159
Com
mands
EXAMPLES
1. To remove the first occurrence of a line starting with [boot] from the SYSTEM.INI file, enter the following command:
wclrline –f –s "[boot]" –o C:\TEMP\OUTPUT.FIL \C:\WINDOWS\SYSTEM.INI
2. To remove all lines that have device= in them from the MYAPP.INI file, enter the following command:
wclrline –s "device=" –o C:\TEMP\OUTPUT.FIL \
C:\WINDOWS\MYAPP.INI
Both example commands write their output to the OUTPUT.FIL file.
SEE ALSOwinsline, wrplline
wco
1–160 Version 3.7
wco Checks out Revision Control System (RCS) revisions.
SYNOPSISwco [arguments] file
DESCRIPTIONwco retrieves a revision from each RCS file and stores it in the corresponding working file.
Paths matching an RCS suffix denote RCS files; all others denote working files. Names are paired as explained in wci.
Revisions of an RCS file can be checked out locked or unlocked. Locking a revision prevents overlapping updates. A revision checked out for reading or processing (such as compiling) need not be locked. A revision checked out for editing and later check-in must normally be locked. Checkout with locking fails if the revision to be checked out is currently locked by another user. (A lock may be broken with wrcs.) Checkout with locking also requires the caller to be on the access list of the RCS file, unless the caller is the owner of the file or the super user, or the access list is empty. Checkout without locking is not subject to access list restrictions and is not affected by the presence of locks.
A revision is selected by arguments for revision or branch number, check-in date and time, author, or state. When the selection arguments are applied in combination, wco retrieves the latest revision that satisfies all of them. If none of the selection arguments is specified, wco retrieves the latest revision on the default branch (normally the trunk, see the –b argument of wrcs). A revision or branch number can be attached to any of the arguments –f, –I, –l, –M, –p, –q, –r, or –u. The arguments –d (date), –s (state), and –w (author) retrieve from a single branch, the selected branch, which is either specified by one of –f, …, –u, or the default branch.
A wco command applied to an RCS file with no revisions creates a zero-length working file. wco always performs keyword substitution.
wco
Tivoli Management Framework Reference Manual 1–161
Com
mands
The working file inherits the read and execute permissions from the RCS file. In addition, the owner’s write permission is turned on, unless –kv is set or the file is checked out unlocked and locking is set to strict (see wrcs).
If a file with the name of the working file exists and has write permission, wco aborts the checkout, asking beforehand if possible. If the existing working file is not writable or –f is given, the working file is deleted without asking.
Arguments
–r [rev] Retrieves the latest revision whose number is less than or equal to rev. If rev indicates a branch rather than a revision, the latest revision on that branch is retrieved. If rev is omitted, the latest revision on the default branch (see the –b argument of wrcs) is retrieved. If rev is $, wco determines the revision number from keyword values in the working file. Otherwise, a revision is composed of one or more numeric or symbolic fields separated by periods. The numeric equivalent of a symbolic field is specified with the –n argument of the commands wci and wrcs.
–l [rev] Same as –r, except that it also locks the retrieved revision for the caller.
–u [rev] Same as –r, except that it unlocks the retrieved revision if it was locked by the caller. If rev is omitted, –u retrieves the revision locked by the caller, if there is one; otherwise, it retrieves the latest revision on the default branch.
–f [rev] Forces the overwriting of the working file; useful in connection with –q. See also “FILE MODES.”
–k kv Generates keyword strings using the default form, such as, $Revision: 5.7 $ for the Revision keyword. A locker’s name is inserted in the value of the Header, Id, and Locker keyword strings only as a file is being locked, for example, by wci–l and wco–l. This is the default.
wco
1–162 Version 3.7
–k kvl Like –k kv, except that a locker’s name is always inserted if the given revision is currently locked.
–k k Generate only keyword names in keyword strings; omit their values. See “KEYWORD SUBSTITUTION.” For example, for the Revision keyword, generate the string $Revision$ instead of $Revision: 5.7 $. This argument is useful to ignore differences due to keyword substitution when comparing different revisions of a file.
–k o Generates the old keyword string, present in the working file just before it was checked in. For example, for the Revision keyword, generate the string $Revision: 1.1 $ instead of $Revision: 5.7 $ if that is how the string appeared when the file was checked in. This can be useful for binary file formats that cannot tolerate any changes to substrings that happen to take the form of keyword strings.
–k v Generates only keyword values for keyword strings. For example, for the Revision keyword, generates the string 5.7 instead of $Revision: 5.7 $. This can help generate files in programming languages where it is hard to strip keyword delimiters like $Revision:$ from a string. However, further keyword substitution cannot be performed once the keyword names are removed, so this argument should be used with care. Because of this danger of losing keywords, this argument cannot be combined with –l, and the owner write permission of the working file is turned off; to edit the file later, check it out again without –k v.
–p [rev] Prints the retrieved revision on the standard output rather than storing it in the working file. This argument is useful when wco is part of a pipe.
–q [rev] Quiet mode; diagnostics are not printed.
–I [rev] Interactive mode; the user is prompted and questioned even if the standard input is not a terminal.
wco
Tivoli Management Framework Reference Manual 1–163
Com
mands
–d date Retrieves the latest revision on the selected branch whose check-in date/time is less than or equal to date. The date and time may be given in free format. The time zone LT stands for local time; other common time zone names are understood. For example, the following dates are equivalent if local time is January 11, 1990, 8 p.m. Pacific Standard Time, eight hours west of Coordinated Universal Time (UTC):
8:00 pm lt4:00 AM, Jan. 12, 1990 note: default is UTC1990/01/12 04:00:00 RCS date formatThu Jan 11 20:00:00 1990 LT output of ctime(3) + LTThu Jan 11 20:00:00 PST 1990 output of dateFri Jan 12 04:00:00 GMT 1990Thu, 11 Jan 1990 20:00:00 –0800Fri-JST, 1990, 1pm Jan 1212-January-1990, 04:00-WET
Most fields in the date and time may be defaulted. The default time zone is UTC. The other defaults are determined in the order year, month, day, hour, minute, and second (most to least significant). At least one of these fields must be provided. For omitted fields that are of higher significance than the highest provided field, the time zone’s current values are assumed. For all other omitted fields, the lowest possible values are assumed. For example, the date 20, 10:30 defaults to 10:30:00 UTC of the 20th of the UTC time zone’s current month and year. The date/time must be quoted if it contains spaces.
–M [rev] Set the modification time on the new working file to be the date of the retrieved revision. Use this argument with care; it can confuse make.
–s state Retrieves the latest revision on the selected branch whose state is set to state.
wco
1–164 Version 3.7
–w [login] Retrieves the latest revision on the selected branch that was checked in by the user with login name login. If the argument login is omitted, the caller’s login is assumed.
–j joinlist Generates a new revision that is the join of the revisions on joinlist. This argument is largely obsoleted by wrcsmerge but is retained for backwards compatibility.
The joinlist is a comma-separated list of pairs of the form rev2:rev3, where rev2 and rev3 are symbolic or numeric revision numbers. For the initial pair, rev1 denotes the revision selected by the arguments –f, …, –w. For all other pairs, rev1 denotes the revision generated by the previous pair. (Thus, the output of one join becomes the input to the next.)
For each pair, wco joins revisions rev1 and rev3 with respect to rev2. This means that all changes that transform rev2 into rev1 are applied to a copy of rev3. This is particularly useful if rev1 and rev3 are the ends of two branches that have rev2 as a common ancestor. If rev1<rev2<rev3 are on the same branch, joining generates a new revision that is like rev3, but with all changes that lead from rev1 to rev2 undone. If changes from rev2 to rev1 overlap with changes from rev2 to rev3, wco reports overlaps as described in merge.
For the initial pair, rev2 can be omitted. The default is the common ancestor. If any of the arguments indicate branches, the latest revisions on those branches are assumed. The arguments –l and –u lock or unlock rev1.
–V n Emulates RCS version n, where n can be 3, 4, or 5. This may be useful when interchanging RCS files with others who are running older versions of RCS. To see which version of RCS your correspondents are running, have them invoke wrlog on an RCS file; if none of the first few lines of output contain the string branch: it is
wco
Tivoli Management Framework Reference Manual 1–165
Com
mands
version 3; if the dates’ years have just two digits, it is version 4; otherwise, it is version 5. An RCS file generated while emulating version 3 will lose its default branch. An RCS revision generated while emulating version 4 or earlier will have a time stamp that is off by up to 13 hours. A revision extracted while emulating version 4 or earlier contains dates of the form yy/mm/dd instead of yyyy/mm/dd and can also contain different white space in the substitution for $Log$.
–x suffixes Uses suffixes to characterize RCS files. See wci for details.
Keyword Substitution
Strings of the form $keyword$ and $keyword:…$ embedded in the text are replaced with strings of the form $keyword:value$ where keyword and value are pairs listed below. Keywords can be embedded in literal strings or comments to identify a revision.
Initially, the user enters strings of the form $keyword$. On checkout, wco replaces these strings with strings of the form $keyword:value$. If a revision containing strings of the latter form is checked back in, the value fields are replaced during the next checkout. Thus, the keyword values are automatically updated on checkout. This automatic substitution can be modified by the –k arguments.
Keywords and their corresponding values:
$Author$ The login name of the user who checked in the revision.
$Date$ The date and time (UTC) the revision was checked in.
$Header$ A standard header containing the full path name of the RCS file, the revision number, the date (UTC), the author, the state, and the locker (if locked).
$Id$ Same as $Header$, except that the RCS file name is without a path.
$Locker$ The login name of the user who locked the revision (empty if not locked).
wco
1–166 Version 3.7
$Log$ The log message supplied during check-in, preceded by a header containing the RCS file name, the revision number, the author, and the date (UTC). Existing log messages are not replaced. Instead, the new log message is inserted after $Log:…$. This is useful for accumulating a complete change log in a source file.
$RCSfile$ The name of the RCS file without a path.
$Revision$ The revision number assigned to the revision.
$Source$ The full path name of the RCS file.
$State$ The state assigned to the revision with the –s argument of wrcs or wci.
FILESwco accesses files much as wci does, except that it does not need to read the working file.
ENVIRONMENT
RCSINIT Arguments prepended to the argument list, separated by spaces. See wci for details.
DIAGNOSTICSThe RCS path name, the working path name, and the revision number retrieved are written to the diagnostic output. The exit status is zero if and only if all operations were successful.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.7; Release Date: 1991/08/19. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991 by Paul Eggert.
SEE ALSOwci, wident, wrcs, wrcsdiff, wrcsmerge, wrlog; Walter F. Tichy, RCS—A System for Version Control, “Software—Practice & Experience 15, 7 (July 1985), 637-654.
wco
Tivoli Management Framework Reference Manual 1–167
Com
mands
UsageLinks to the RCS and working files are not preserved.
There is no way to selectively suppress the expansion of keywords, except by writing them differently. In nroff and troff, this is done by embedding the null character \& into the keyword.
BUGSThe –d argument sometimes gets confused, and accepts no date before 1970.
wconnect
1–168 Version 3.7
wconnect Connects two Tivoli Management Regions (TMRs).
SYNOPSISwconnect [–u] [–m mode] [–r encrypt_level] –s server region_num
wconnect [–nu] [–c encrypt_level] [–l login] [–m Two-way | Managing | Managed] [–r encrypt_level] server
DESCRIPTIONThe wconnect command establishes a connection between the TMR servers in two TMRs. The first usage of wconnect shown in the synopsis performs a secure connection. To complete the connection, this command must be run on both the TMR servers being connected. The second usage performs a remote connection. This command is run on only one TMR server. If the connection being made is to be a one-way connection, the TMR server from which the remote connection was performed becomes the managing server.
TMRs can be connected in a one-way connection or a two-way connection. With a one-way connection, one server is the managing server and one is the managed server. An administrator on the managing server can manage any resources on either the managing server or the managed server. However, an administrator on the managed server cannot manage resources on the managing server. With a two-way connection, administrators on either server can manage any resources of the other server.
Authorization
super
Arguments
–c encrypt_level Specifies the interregion encryption level that is in use
in the local TMR. Valid encryption levels are simple, none, or DES. If the encryption level is none, no key is required. If the level is simple or DES, the command prompts for the key in use. The encryption key is the same as the installation password specified during the
wconnect
Tivoli Management Framework Reference Manual 1–169
Com
mands
server installation. The encryption level must be the same as that specified during the TMR server installation. The default encryption level is simple.
–l login Supplies a login name for the remote connection process. This login must be a valid login for a user on the remote server, and the user must have a Tivoli administrator with the super role defined in the remote TMR. If the –l argument is specified, the command prompts for a password. If the trusted hosts facility is used, do not type the password. Instead, press the Enter key to continue.
–m mode Specifies the mode of connection to be established between TMRs. Valid connection modes are as follows:
Two-way Establishes a two-way connection between TMRs. In a two-way connection, both TMR servers have managing authority over the resources in both TMRs. This is the default value.
Managing Establishes a one-way connection with the local TMR server as the managing server. The local TMR server can manage resources in the remote TMR, but the remote TMR server cannot manage resources in the local TMR.
Managed Establishes a one-way connection with the local TMR server as the managed server. This option is valid on secure connections only. For remote connections, the local server can be only a managing server.
–n Instructs Tivoli not to prompt for passwords. You can use this argument only when you have trusted host access and do not require an encryption key.
wconnect
1–170 Version 3.7
Note: Because Windows NT does not have trusted host access, this argument cannot be used when connecting Windows NT TMR servers.
–P port Specifies the port number to use for communication with the TMR server if different from the local object dispatcher’s port.
Note: This option is meant for use in development and test environments only. It should not be used in a production environment.
–r encrypt_level Specifies the encryption level in use in the remote
TMR. Valid encryption levels are simple, none, or DES. If the encryption level is none, no key is required. If the level is simple or DES, the command prompts for the key in use. The encryption key is the same as the installation password specified during the server installation. The encryption level must be the same as that specified during the TMR server installation. The default encryption level is simple.
–s Establishes the connection using the secure connection process. This requires running wconnect –s on both TMR servers in the connection.
–u Updates resources between TMRs in a two-way connection or from the remote TMR in a one-way connection.
region_num Specifies the region number of the remote TMR.
server Specifies the name of the TMR server in the remote TMR.
wconnect
Tivoli Management Framework Reference Manual 1–171
Com
mands
EXAMPLES
1. The following example performs a remote two-way connection. Both TMR servers use simple encryption. The administrator running this command has the login sally on the remote server, elbert. Resource information will be exchanged between the servers as soon as the connection is complete.
wconnect –u –c simple –l sally –m Two-way –r simple\ \elbert
2. The following example performs a remote one-way connection. The local server uses no encryption, but the remote server, cook, uses simple encryption. The local server becomes the managing server and the remote server becomes the managed server. Resource information will be updated on the local server.
wconnect –u –c none –m Managing –r simple cook
3. The following example performs a secure two-way connection. The remote server, pinatubo, uses simple encryption (by default). The region number of the remote server is 4004418954. Resource information will be exchanged between the servers when the connection has been completed.
wconnect –u –s pinatubo 4004418954
To complete the connection, you must run wconnect on the remote server also. The following command must be run from pinatubo. In this example, the encryption level is specified with the –r argument while the previous command simply used the default value. Resource information will be updated between servers.
wconnect –u –r simple –s everest 4004598145
4. The following example performs a secure one-way connection. The remote server, meiron, uses simple encryption (by default). The region number of the remote server is 0003432265. The local server will be the managed server. Resource information will be exchanged between the servers as soon as the connection is complete.
wconnect –u –m Managed –s meiron 0003432265
wconnect
1–172 Version 3.7
To complete the connection, you must run wconnect on the remote server also. The following command must be run from meiron. meiron will be the managing server.
wconnect –u –m Managing –s space 4004598145
Note: If you make a one-way connection using the secure connection process and the first server you run wconnect on is specified as the managing server instead of the managed server, you must run the wlsconn –u command to complete the exchange of connection information on the managing server.
SEE ALSOwlsconn, wdisconn, wupdate
wcpcdrom
Tivoli Management Framework Reference Manual 1–173
Com
mands
wcpcdromCopies installation images from a CD to a system directory.
SYNOPSISwcpcdrom [–i start_index] [–c] [–n] cdrom_list new_cdrom_dir [interp_list]
DESCRIPTIONThe wcpcdrom command copies Tivoli installation images from a Tivoli CD into a system directory, new_cdrom_dir. Using this command, you can copy the contents of a CD to a system directory, merge multiple CD images in a system directory, or copy a single interpreter type from one or more CDs to a system directory. If, for example, you want to build an installation image for the HP-UX 10.01 version of the Tivoli Management Framework and all the Tivoli applications, you could use this command to create a single directory that contains only the HP-UX 10.01 binaries and libraries for all the Tivoli applications you want to install. You can then install all the applications from that directory.
By default, wcpcdrom creates symbolic links to the images on the CD. If you are copying images from multiple CDs, you should use the –c argument, which copies the files instead of creating the symbolic link.
When copying images from multiple CDs, you must also use the –i start_index argument. This argument indicates the number that wcpcdrom should start with when numbering packets in the new_cdrom_dir. For example, suppose you have already copied one Tivoli CD to a directory. The directory contains file1.pkt through file95.pkt. When you copy the second CD, you must use the –i start_index argument to avoid overwriting the existing files. You might, for example, specify wcpcdrom –i 96. Each packet on the second CD is then numbered sequentially starting at file96.pkt.
Once new_cdrom_dir contains the images you want, you can copy the full image onto a tape using the following command:cd new_cdrom_dir tar–cvhf tape_device
To install from the new image, create an install_dir directory and run the wpreinst command in the same way that you would install from the CD.
wcpcdrom
1–174 Version 3.7
See the Tivoli Enterprise Installation Guide for installation procedures.
Authorization
No special authorization is required to use this command.
Arguments
–i start_index Indicates the number at which wcpcdrom should begin numbering packets copied into new_cdrom_dir. start_index can be any number 1 through 9999.
–c Copies the CD images instead of creating symbolic links to the CD.
–n Shows what wcpcdrom will do when executed. No files are changed when this argument is specified.
cdrom_list Identifies the path to the CD. Multiple paths must be separated by commas.
new_cdrom_dir Identifies the directory into which the file packets are copied.
interp_list Identifies the interpreter type to be copied from the CD. Multiple interpreter types must be separated by a space. If no interp_list is given, all interpreter types are copied. For a complete list of valid interpreter types, see the Tivoli Enterprise Installation Release Notes.
EXAMPLES
1. The following example copies the contents of CD cdrom1 to the /tmp/tiv_install directory:
wcpcdrom –c /mycdrom/cdrom1 /tmp/tiv_install
2. The following example copies only the solaris2 interpreter type from the CD cdrom2 to the /tmp/tme_install directory. File packets will be numbered sequentially starting at 96.
wcpcdrom –c –i 96 /mycdrom/cdrom2 /tmp/tme_install \solaris2
wcpcdrom
Tivoli Management Framework Reference Manual 1–175
Com
mands
3. The following example copies the HP-UX 10.01 Tivoli Management Framework file packets from /mycdrom/tmp_cdrom and the HP-UX 10.01 Tivoli application file packets from /urcdrom/apps_cdrom. All file packets will be copied to the /home/new_dir directory. File packets will be numbered sequentially starting at 1.
wcpcdrom –c –i 1 /mycdrom/tmp_cdrom, /urcdrom/apps_cdrom \/home/new_dir hpux
SEE ALSO
wcrtimage
wcpyfile
1–176 Version 3.7
wcpyfileEnables a NetWare configuration program (.NCF) to copy a file. This command should be run from an endpoint.
SYNOPSISwcpyfile –s src_path –d dest_path
DESCRIPTIONThe wcpyfile command was created in support of .NCF configuration programs. It enables you to copy files from one volume or directory to another on the NetWare machine from within an .NCF configuration program.
Arguments
–s src_path Specifies the full path to the source file.
–d dest_path Specifies the full path to the destination file.
EXAMPLESFrom an .NCF configuration program, enter the following command in the program to copy the SYS:\TEMP\FILE.NLM file to the SYS:\SYSTEM\FILE.NLM file:wcpyfile –s SYS:\TEMP\FILE.NLM –d SYS:\SYSTEM\FILE.NLM
wcrtadmin
Tivoli Management Framework Reference Manual 1–177
Com
mands
wcrtadminCreates a new Tivoli administrator.
SYNOPSISwcrtadmin –l login… [–n noticegroup]... [–r group,role1:role2...] [–u user_id [–g group_id]]… name
DESCRIPTIONThe wcrtadmin command creates a new Tivoli administrator.
Authorization
senior
Arguments
–l login Sets up a Tivoli login for the new administrator. The login can be entered in one of the following forms:
■ username
■ username@ManagedNode
■ NTdomain\username
■ NTdomain\username@ManagedNode
■ kerberos_name:realm
If only username or NTdomain\username is specified, the user can log in from any system in the Tivoli Management Region (TMR). If username@ManagedNode or NTdomain\username@ManagedNode is specified, the user can log in only from the specified host.
–n noticegroup Sets up a notice group subscription for the new administrator. You can specify more than one notice group.
–r group,role1:role2 Gives the new administrator roles in the specified group. This option must be entered in the form of @group,role1:role2 (for example,
wcrtadmin
1–178 Version 3.7
@Administrator,admin:user or @DefaultRegion,super). To specify a role in a single instance of a group, specify the group type followed by the instance name. Both names must be colon separated. For example, @PolicyRegion:MyRegion,super:senior specifies super and senior roles in policy region MyRegion. To specify TMR roles, use the string “global” (for example, –r global,user).
–u user_id Sets the principal user ID (UID) for the new administrator. user_id can be entered in one of the following forms:
■ username
■ username@ManagedNode
■ NTdomain\username
■ NTdomain\username@ManagedNode
■ kerberos_name:realm
–g group_id Sets the principal group ID (GID) for the new administrator.
name The label of the new administrator. This label displays with the Administrator icon in the Administrators window. Administrator names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
EXAMPLES
1. The following example creates an administrator with the Tivoli login kimiko on system ohio, membership in the Tivoli- Authorization notice group, the admin authorization role in the Testing policy region, and the label Kimiko:
wcrtadmin –l kimiko@ohio –n Tivoli-Authorization \–r @PolicyRegion:Testing,admin Kimiko
wcrtadmin
Tivoli Management Framework Reference Manual 1–179
Com
mands
2. The following example creates an administrator under the principals callahan@sthelens and callahan@dogma with the roles user in TMR, the roles super, admin, and user in DefaultRegion, the roles super and senior in group Administrators, and the roles super, senior, admin, user, and backup in the MyRegion policy region. callahan is added as a member of the Tivoli Authorization group. The administrator runs as principal user ID callahan and principal group ID staff. The administrator’s label is Steve Callahan.
wcrtadmin –l callahan@sthelens –l callahan@dogma \–n "Tivoli Authorization" \–r global,user –r @DefaultRegion,super:admin:user \–r /Administrators,super:senior \–r @PolicyRegion:MyRegion,super:senior:admin:user:backup \–u callahan –g staff "Steve Callahan"
SEE ALSOwgetadmin, wsetadmin
wcrtgate
1–180 Version 3.7
wcrtgateCreates an endpoint gateway.
SYNOPSISwcrtgate {[–h managed_node] [–i IPX_socket_num] [–n gateway_name] [–P protocols_list] [–p TCPIP_port] [–t default_session_timeout]}
DESCRIPTIONThe wcrtgate command creates a new endpoint gateway on the specified managed node. You must specify at least one of these arguments.
Authorization
senior
Arguments
–h managed_node Specifies the name of the managed node on which the gateway will be created. If this argument is not used, the gateway is created on the managed node from which the command was given.
–i IPX_socket_num Specifies the port on which the gateway listens for Sequenced Packet Exchange (SPX) packets. The gateway also listens for Internetwork Packet Exchange (IPX) packets on the IPX_socket_num –1 port.
–n gateway_name Specifies the name of the gateway. If this argument is not used, the gateway name will be managed_node-gateway.
–P protocols_list Specifies the supported protocols for the specified gateway. Multiple protocols must be separated by commas, for example, protocol1,protocol2.
wcrtgate
Tivoli Management Framework Reference Manual 1–181
Com
mands
–p TCPIP_port Specifies the Transmission Control Protocol/ Internet Protocol (TCP/IP) port number through which the gateway will communicate with its assigned endpoints. The default is port 9494.
Note: Do not use the same port number used by the proxy managed node or by the endpoints.
–t default_session_timeout Sets the session timeout period used during downcalls from the gateway to an endpoint. The specified time represents the amount of time the gateway will wait for a response from the endpoint.
EXAMPLES
1. The following example creates an endpoint gateway on managed node pearl. The resulting gateway is named pearl-gateway and communicates on default port 9494.
wcrtgate –h pearl
2. The following example creates an endpoint gateway named gems on managed node diamond:
wcrtgate –h diamond –n gems
3. The following example creates an endpoint gateway named subnet30-gateway on managed node vernon that communicates through port 8432.
wcrtgate –h vernon –n subnet30-gateway –p 8432
4. The following example creates an endpoint gateway on managed node vernon that supports both TCP/IP and IPX protocols. It communicates with TCP/IP endpoints on port 9999 and with IPX endpoints on port 6000:
wcrtgate –h vernon –P TCPIP,IPX –p 9999 –i 6000 –n gems
SEE ALSO
wdelgate
wcrtjob
1–182 Version 3.7
wcrtjobCreates a job in a task library.
SYNOPSISwcrtjob –j job_name –l library_name –t task_name –M mode [–s interval –n number] –m timeout –o output_format [–D | –d mannode_name –f file_name] [–h mannode_name] [–p prof_manager_name]
DESCRIPTIONThe wcrtjob command creates a job using the specified task. A job is a resource in Tivoli that can be run repeatedly.
Authorization
admin, senior, super
Arguments
–j job_name The name of the job being created. Job names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
–l library_name Specifies the task library containing the task to be included in the job.
–t task_name The name of the task to include in the job.
–M mode Specifies the mode in which the job will be run. Valid options are as follows:
serial Runs the job on one managed node at a time.
parallel Runs the job on all specified managed nodes and any subscribers simultaneously.
staged Runs the job on groups of managed nodes at specified intervals.
wcrtjob
Tivoli Management Framework Reference Manual 1–183
Com
mands
–s interval Specifies the number of seconds between when the task runs on one group of managed nodes and when it runs on the next group. You must specify a value for this option if you selected staged mode.
–n number Specifies the number of managed nodes in each group in staged mode. You must specify a value for this option if you selected staged mode.
–m timeout The number of seconds that the task library waits for results to be returned from the task. This argument does not affect the execution of the job. If you are using staged mode, the timeout must be smaller than the interval time.
–o output_format Defines the format of the job output. The job output contains a summary of the job on each managed node. Task execution output format is specified with an octal number from 0 to 17. The format is constructed by adding the value of the desired output. For example, to print the task’s return code and standard output, enter –o 12. Output values are as follows:
01 Prints a descriptive header for each record
02 Prints the task’s return code
04 Prints the standard error output
10 Prints the standard output
–D Displays the job output to the screen.
–d mannode_name Specifies the managed node on which to save to the job output.
–f file_name Specifies the file name in which to save the job output.
–h mannode_name Specifies the managed nodes on which to run the job.
wcrtjob
1–184 Version 3.7
–p prof_manager_name Specifies the profile managers on which the job will run.
EXAMPLES
1. The following example creates a job called date_job. The job includes task date_task, which is contained in task library my_tasks. The job runs in parallel on managed nodes that subscribe to the marketing profile manager. The job runs on each managed node for 120 seconds before it times out. The output of the task displays to the screen.
wcrtjob –j date_job –t date_task –l my_tasks \–M parallel –m 120 –p marketing –o 017 –D
2. The following example creates a job called date_job2. The job includes task date_task, which is contained in task library my_tasks. The job runs in parallel on managed node bald. The job runs for 120 seconds before it times out. The job’s output is saved to a file named /tmp.date_job2.output on managed node bald.
wcrtjob –j date_job2 –t date_task –l my_tasks \–M parallel –m 120 –h bald –o 017 –d bald \–f /tmp/date_job2.output
SEE ALSOwcrttask, wruntask, wdeljob
wcrtpol
Tivoli Management Framework Reference Manual 1–185
Com
mands
wcrtpolCreates a new policy object for a class.
SYNOPSISwcrtpol [–d | –v] class name [parent]
DESCRIPTIONThe wcrtpol command creates a new policy default or policy validation object for a class. The new policy object inherits its first set of methods and attributes from an existing class policy object. Use the wgetpolm and wputpolm commands to customize the new policy object.
Authorization
senior, super
Arguments
–d Creates a policy default object. This action is the default unless the –v argument is present.
–v Creates a policy validation object.
class The new policy object’s class.
name The new policy object’s name. Policy object names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
parent The label of an existing class policy object from which the new policy object inherits its initial methods and attributes. The default parent is the default policy object for the class.
EXAMPLESThis example creates a policy validation object for ProfileManager. The object is named Restricted and inherits from the BasicProfileManager policy object. wcrtpol –v ProfileManager Restricted BasicProfileManager
wcrtpol
1–186 Version 3.7
SEE ALSOwcrtpr, wdelpr, wchkpol, wdelpol, wgetdfpol, wgetpolm, wls, wlspolm, wputpolm
wcrtpr
Tivoli Management Framework Reference Manual 1–187
Com
mands
wcrtprCreates a policy region.
SYNOPSISwcrtpr [–a admin…] [–s region] [–m resource…] name
DESCRIPTIONThe wcrtpr command creates a policy region. When a policy region is created with this command, policy validation is disabled for all resource types. Use the wsetpr command to enable policy validation.
Authorization
senior; senior and policy when the –m argument is issued.
Arguments
–a admin… Adds the new policy region to the specified administrator’s desktop. You can use –a admin multiple times to add the region to the desktops of several administrators.
–s region Creates the new policy region as a subregion of region. The new policy region inherits the supported classes of its parent region. If you omit the –s argument, wcrtpr creates the region as a top-level region.
–m resource… Specifies a resource to be added to the new policy region’s list of managed resources. You can use –m multiple times to add several managed resources. The policy authorization role is required if the –m argument is used.
name The name of the new policy region. Policy region names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
wcrtpr
1–188 Version 3.7
EXAMPLES
1. The following example creates a top-level policy region and automatically adds it to the root administrator’s desktop:
wcrtpr –a Root_ceridwen-region new-region
2. The following example creates a subregion under the default region, and makes the ManagedNode resource type a managed resource:
wcrtpr –s /Regions/test-region –m ManagedNode node-region
SEE ALSOwdelpr, wchkpol, wcrtpol, wdelpol, wgetdfpol, wgetpolm, wlspolm, wputpolm
wcrtprf
Tivoli Management Framework Reference Manual 1–189
Com
mands
wcrtprfCreates a new profile or clones an existing profile.
SYNOPSISwcrtprf [–c source] profile_manager type profile_name
DESCRIPTIONThe wcrtprf command creates a configuration profile of the type specified in the type option. The profile is created using the name specified in profile_name in the profile manager specified in profile_manager.
If source is specified, the wcrtprf command clones an existing profile of the same type. If source is not specified, the new profile will be initialized empty.
Authorization
senior or super
Arguments
–c source Specifies the name of an existing profile from which to clone the new one. Valid formats for the source argument include the following:
■ @prof_name
■ @profile_type:prof_name
■ /Regions/PolicyRegionName/prof_manager_name/prof_name
profile_manager Specifies the name of the profile manager in which to create the profile. Valid formats for the profile_manager argument include the following:
■ @prof_manager_name
■ @ProfileManager:prof_manager_name
■ /Regions/PolicyRegionName/prof_manager_name
wcrtprf
1–190 Version 3.7
type The type of profile to create. The type can be UserProfile, GroupProfile, HostNamespace, NisDomain, SentryProfile, SoftwarePackage, or FilePackage.
profile_name The name of the new profile. Profile names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
EXAMPLES
1. The following example creates a Tivoli Distributed Monitoring profile called DiskSpace. The profile will be created in the Development profile manager.
wcrtprf @ProfileManager:Development SentryProfile \DiskSpace
2. The following example clones the DiskSpace profile into the Marketing profile manager.
wcrtprf –c @SentryProfile:DiskSpace \@ProfileManager:Marketing SentryProfile OurDiskSpace
SEE ALSOwcrtprfmgr, wgetsub, wlspol, wpopulate, wgetprf, wdistrib, wsub, wunsub, wvalidate
wcrtprfmgr
Tivoli Management Framework Reference Manual 1–191
Com
mands
wcrtprfmgrCreates a profile manager.
SYNOPSISwcrtprfmgr pol_region name
DESCRIPTIONThe wcrtprfmgr command creates a profile manager using the name specified in the name argument. The profile manager is created in the policy region specified in the pol_region argument.
Note: To specify whether or not a profile manager runs in dataless mode, use the wsetpm command.
Authorization
senior or super
Arguments
pol_region The policy region in which to create the profile manager:
■ @pol_region
■ @PolicyRegion:pol_region
■ /Regions/pol_region
name The name of the new profile manager. Profile manager names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
EXAMPLESThe following example creates the Development profile manager in the Dallas policy region: wcrtprfmgr @Dallas Development
SEE ALSOwcrtprf, wgetsub, wlssub, wpopulate, wgetprf, wdistrib, wsetpm, wsub, wunsub, wvalidate
wcrtqlib
1–192 Version 3.7
wcrtqlibCreates a query library.
SYNOPSISwcrtqlib policy_region query_lib
DESCRIPTIONThe wcrtqlib command creates a new query library in the specified policy region.
Authorization
senior or super
Arguments
policy_region Specifies the name of the policy region in which to create the query library.
query_lib Specifies the name of the new query library.
EXAMPLESThe following example creates a query library called NewQueries in the amon-sul-Region policy region.wcrtqlib amon-sul-Region NewQueries
SEE ALSOwcrtquery, wgetquery, wsetquery, wruninvquery, wrunquery, wdel
wcrtquery
Tivoli Management Framework Reference Manual 1–193
Com
mands
wcrtqueryCreates a query.
SYNOPSISwcrtquery [–d desc] [–r repository] [–v view] [–c column]… [–i | –s | –w where_clause] [–x] query_lib query_name
DESCRIPTIONThe wcrtquery command creates a new query in a query library. You can specify a description for the query, a repository, a view, the columns to query, and SQL search (or where) clauses. You can specify the optional where clauses through either standard input or on the command line.
The defaults for the configuration repository, view, and columns are supplied by the policy defaults in the policy region that contains the query library.
You can view and edit these attributes with the wgetquery and wsetquery commands, or from the Tivoli desktop.
Authorization
admin, senior, or super
Arguments
–d desc Specifies a description of the query.
–r repository Specifies the name of the configuration repository from which to retrieve information.
–v view Specifies the name of the view or table from which to retrieve information.
–c column Specifies the column or columns from which to retrieve information. To include more than one column, use multiple –c clauses. The columns in the output will be ordered according to how you enter them here.
–i Reads the nonstructured where clause from standard input.
wcrtquery
1–194 Version 3.7
–s Reads the structured where clause from standard input. The clause should be in the following format:
[AND | OR] [NOT] Column_Name {= | != | < | <= | > | >= | LIKE | IN} Column_Value
–w where_clause Provides a where clause on the command line.
–x Specifies that the output of the query will not contain duplicate rows.
query_lib Specifies the name of the query library in which to create the query.
query_name Specifies the name of the new query.
EXAMPLES
1. The following example creates a query named DOS-machines in the query library named NewQueries. This query uses a structured where clause, read from standard input, to find information about machines running DOS. The query looks in the inventory repository in the MACHINE_TYPE view, and returns information from the PROCESSOR_TYPE and OPERATING_SYSTEM columns for every instance of BOOTED_OS_NAME that has a value of DOS.
wcrtquery –d "Find all DOS machines" –r inventory –v \MACHINE_TYPE –c PROCESSOR_TYPE –c OPERATING_SYSTEM –s \NewQueries \DOS-machines <<EOF
(BOOTED_OS_NAME = 'DOS')EOF
2. The following example creates the same query, except that an unstructured where clause specifies that the results will be sorted by HARDWARE_SYSTEM_ID.
wcrtquery –d "Find all DOS machines" –r inventory –v \MACHINE_TYPE –c PROCESSOR_TYPE –c HARDWARE_SYSTEM_ID \–w "(BOOTED_OS_NAME = 'DOS') ORDER BY HARDWARE_SYSTEM_ID" \NewQueries DOS-machines
wcrtquery
Tivoli Management Framework Reference Manual 1–195
Com
mands
SEE ALSOwcrtqlib, wgetquery, wsetquery, wruninvquery, wrunquery, wdel
wcrtrim
1–196 Version 3.7
wcrtrimCreates a RDBMS Interface Module (RIM) object.
SYNOPSISwcrtrim [–i] –v vendor [–h host_name | –o host_oid] –d database –u user –H db_home –s server_id [–I instance_home] rim_name
DESCRIPTIONThe wcrtrim command creates a new RIM object on a specific managed node. If you use the –h or –o argument, specify a managed node that is local to the Tivoli Management Region (TMR) where you enter the wcrtrim command and where the RIM object will reside. If you do not specify either the name or the object ID of a managed node, the RIM object is created on the TMR server. The instance home argument is required only if the database is DB2.
You cannot change the vendor for a RIM object after it has been created. If you need to change the vendor, you must delete the RIM object and create a new one.
Authorization
senior or super in TMR
Arguments
–i Reads the database password from standard input. If you specify this argument, the password can be of any length. If you do not specify this argument, you will be prompted for a password, and the password must be limited to eight characters.
–v vendor Specifies the name of the database vendor that the RIM object will represent. Acceptable values include Informix, Oracle, Sybase, DB2, and MS_SQL.
–h host_name Specifies the name of a managed node on which the RIM object will reside. The managed node must be in the local TMR. If you do not use either this or the –o argument, the RIM object will be created on the TMR server.
wcrtrim
Tivoli Management Framework Reference Manual 1–197
Com
mands
–o host_oid Specifies the managed node object ID as the location for the RIM object. The object ID must be in the local TMR. If you do not use either this or the –h argument, the RIM object will be created on the TMR server.
–d database Specifies the name (database ID) of the database to which the RIM object will connect.
–u user Specifies the name of the database user that the RIM object will use. If you are using DB2, specify a valid UNIX user.
–H db_home Specifies the path to the database home directory. This argument actually sets the environment variables ORACLE_HOME, SYBASE, and DB2DIR for Oracle, Sybase, and DB2, respectively.
–s server_id Specifies the server ID for the database. This argument actually sets the environment variables TWO_TASK, DSQUERY, and DB2COMM for Oracle, Sybase, and DB2, respectively. For Microsoft SQL Server, this is the name of the RDBMS server machine.
–I instance_home For DB2 only, specifies the path and name of the instance to which the RIM object will connect.
rim_name Specifies the name of the RIM object to be created.
EXAMPLES
1. The following example interactively creates a RIM object:
wcrtrim –v Oracle –h amon-sul –d amar –u tivoli –H \/tivoli/drm/2/amishra/ORACLE –s invdb.world inventory
RDBMS password:
2. The following example creates the same RIM object, but reads the password from a file:
wcrtrim –i –v Oracle –h amon-sul –d amar –u tivoli \–H /tivoli/drm/2/amishra/ORACLE –s invdb.world inventory \< ./passwd
wcrtrim
1–198 Version 3.7
SEE ALSOwgetrim, wsetrim, wsetrimpw, wdel
wcrttask
Tivoli Management Framework Reference Manual 1–199
Com
mands
wcrttaskCreates a task in a task library.
SYNOPSISwcrttask –t task_name –l lib_name [–g group_name] [–u user_name] –r role [–c comments] {–i interp_type mannode_name filename}…
wcrttask [–F filename] –t task_name –l lib_name [–u user_name] [–g group_name] –r role
DESCRIPTIONThe wcrttask command creates a task in the specified task library. A task is a method you run on specified managed nodes and their subscribers. Each time you run the task you must specify the run information.
If you specify only the –t and –l arguments, the task is created in the specified task library but is not executed. To create the task and run it immediately, you must specify the –i interp_type mannode_name filename set of options. You can specify the set multiple times, once for each platform on which the task will run.
Authorization
admin, senior, super
Arguments
–F filename Specifies a file that contains information about an existing task. The specified file must be a tar file that is created by running the wgettask command. If this argument is used, the specified file is imported and a new task is created using the information in the file. This argument is useful when importing a task from one Tivoli environment to another.
–t task_name Specifies the name of the new task. Task names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
–l lib_name Specifies the task library in which to create the task.
wcrttask
1–200 Version 3.7
–g group_name Specifies the name of the group under which the task will run.
–u user_name Specifies the name of the user under which the task will run. If you use an asterisk (*) to set user_name to the current user ID (UID), enclose the asterisk in single quotation marks (for example, –u '*').
–r role Specifies the authorization roles required to run the task. Multiple roles can be specified in a colon-separated list, for example, admin:senior:super.
–c comments Adds any explanatory comments that help identify the task and its purpose.
–i Defines the information required to execute the new task on a managed node. You must supply the following values with the –i argument:
interp_type Specifies the interpreter type of the platform on which the task is to be run.
mannode_name Specifies the managed node containing the executable for the specified platform.
filename Specifies the name of the executable to be run on the specified platform.
EXAMPLES
1. The following example creates a task called date_task in the task library my_tasks. Administrators must have the super, senior, or user role to execute this task. The task will run on the Solaris platform. The executables for this task are located in /bin/date on managed node bald. A comment is also included.
wcrttask –t date_task –l my_tasks \–r super:senior:user –i solaris2 bald /bin/date \–c "This task runs the /bin/date command"
wcrttask
Tivoli Management Framework Reference Manual 1–201
Com
mands
2. The following example creates a task called find_cores in the task library my_tasks. This task requires the super role. The task will run on the default platform. The task’s executable files are located in /tmp/find_cores.sh on managed node bald. The task will run as root.
wcrttask –t find_cores –l my_tasks –r super \–i default bald /tmp/find_cores.sh –c "This task finds \core files and runs as root" –u root
SEE ALSOwcrtjob, wdeltask, wgettask, wtll
wcrttlib
1–202 Version 3.7
wcrttlibCreates a task library.
SYNOPSISwcrttlib library_name pr_name
DESCRIPTIONThe wcrttlib command creates a task library in the specified policy region.
Authorization
admin, senior, super
Arguments
library_name The name of the task library being created. Task library names can include any alphanumeric character, an underscore (_), a dash (–), a period (.), and a space.
pr_name The name of the policy region in which to create the task library.
EXAMPLESThe following example creates a task library named my_tasks in the policy region bald-region. wcrttlib my_tasks bald-region
SEE ALSOwcrttask, wcrtjob
wdate
Tivoli Management Framework Reference Manual 1–203
Com
mands
wdatePrints the current date and time of the managed node.
SYNOPSISwdate host_name
DESCRIPTIONThe wdate command prints the current date and time (Greenwich Mean Time [GMT]) of the managed node specified by host_name. The date is printed in the locale-dependent format.
Authorization
user, admin, senior, super
Argument
host_name The name of the host whose date to print.
EXAMPLESThe following example shows the current date and time of the managed node bald: wdate baldMon Nov 21 16:27:09 GMT 1998
SEE ALSOwdiskspace, whostid, wifconfig, winstdir, winterp, wmannode, wmemsize, wping, wtimezone, wuname, wxterm
wdel
1–204 Version 3.7
wdelDeletes objects from the Tivoli database.
SYNOPSISwdel [–I] label…
DESCRIPTIONThe wdel command deletes one or more objects. The wdel command is intended for low-level administration of the Tivoli object database. The default is for the command to fail if a suboperation fails. Tivoli provides the following commands for commonly performed actions:
wdelep Deletes an endpoint from the Tivoli database.
wdeljob Deletes a job from a task library.
wdelpol Deletes a default policy object.
wdelpr Deletes a policy region.
wdelrealm Deletes an HTTP realm.
wdelsched Removes a job from the scheduler.
wdeltask Deletes a task from the task library.
wrmnode Removes a managed node from the Tivoli database.
Authorization
admin, senior, super
Arguments
–I Ignores all failed suboperations, allowing the command to continue. This argument is useful only when multiple labels are passed to the command. The –I argument allows a deletion to fail for individual objects, but the command continues to the next object to be deleted. Without this argument, if a deletion fails for an individual object, the command restores any objects already deleted, and then the command terminates with error.
wdel
Tivoli Management Framework Reference Manual 1–205
Com
mands
label… The label of the object to be deleted. The label option can be either an object path or a registered name. An object path can be an absolute path (starting at the “/” collection), a relative path (relative to the current working collection), or a simple name (to be found in the current working collection).
EXAMPLESThe following example deletes the profile manager pm2 from the sevenup-region policy region using its absolute path.wdel /Administrators/vwilburn/sevenup-region/pm2
SEE ALSOwdelep, wdelgate, wdeljob, wdelpol, wdelpr, wdelrealm, wdelsched, wdeltask, wrm, wrmnode
wdelep
1–206 Version 3.7
wdelepDeletes an endpoint.
SYNOPSISwdelep [–d] endpoint_name
DESCRIPTIONThe wdelep command deletes the endpoint specified by endpoint_name from the Tivoli database. Using the –d argument stops the lcfd daemon running on the endpoint.
Note: If you are deleting an endpoint from a managed, one-way interconnected Tivoli Management Region (TMR), you must first unsubscribe the endpoint from all profile managers in the managing TMR. Use the wlssub command to list all profile managers to which the endpoint subscribes. Use the wunsub command from the managing TMR to delete all the endpoint’s subscriptions.
Authorization
senior or super in the endpoint’s policy region
Arguments
–d Deletes the lcf.dat file from the endpoint system and shuts down lcfd.exe.
endpoint_name Specifies the name of the endpoint to be deleted.
EXAMPLESThe following example deletes endpoint ruby: wdelep ruby
SEE ALSOwep, wlssub, wunsub
wdelgate
Tivoli Management Framework Reference Manual 1–207
Com
mands
wdelgateDeletes an endpoint gateway.
SYNOPSISwdelgate gateway_name
DESCRIPTIONThe wdelgate command deletes the endpoint gateway specified by gateway_name.
Arguments
gateway_name Specifies the name of the gateway to be deleted.
Authorization
senior
EXAMPLESThe following example deletes gateway gems:wdelgate gems
SEE ALSOwcrtgate
wdeljob
1–208 Version 3.7
wdeljob Deletes a job from a task library.
SYNOPSISwdeljob job_name lib_name
DESCRIPTIONThe wdeljob command deletes a job from the task library.
Authorization
admin, super, senior
Arguments
job_name Specifies the name of the job to be deleted.
lib_name Specifies the name of the task library where the job resides.
EXAMPLESThe following example deletes job date_job from task library my_tasks. wdeljob date_job my_tasks
SEE ALSOwcrtjob, wdeltask
wdelpol
Tivoli Management Framework Reference Manual 1–209
Com
mands
wdelpol Deletes a default policy object.
SYNOPSISwdelpol [–d | –v] class name
DESCRIPTIONThe wdelpol command deletes the specified policy default object or policy validation object for the resource with the specified label.
Authorization
senior or super
Arguments
–d Deletes the resource’s policy default object. This argument is the default if –v is not specified.
–v Deletes the resource’s policy validation object.
class The label of the class of managed resource whose policy object is to be deleted.
name The name of the policy object that is to be deleted.
EXAMPLESThe following example deletes the restricted policy validation object for ProfileManager: wdelpol –v ProfileManager Restricted
SEE ALSOwcrtpr, wdelpr, wchkpol, wcrtpr, wgetdfpol, wgetpolm, wlspol, wlspolm, wputpolm
wdelpr
1–210 Version 3.7
wdelpr Deletes a policy region.
SYNOPSISwdelpr region
DESCRIPTIONThe wdelpr command deletes the policy region specified in the region option.
Authorization
The senior role in the policy region to be deleted
Argument
region The policy region to be deleted. The policy region must be empty.
EXAMPLESEach of the following examples deletes the DefaultRegion policy region: wdelpr /Regions/DefaultRegion
wdelpr @PolicyRegion:DefaultRegion
wdelpr @DefaultRegion
SEE ALSOwcrtpr
wdelrealm
Tivoli Management Framework Reference Manual 1–211
Com
mands
wdelrealmDeletes a registered HTTP 1.0 authentication realm. The HTTP daemon must be restarted before the realm is actually deleted.
SYNOPSISwdelrealm –d RealmDir
DESCRIPTIONThe wdelrealm command removes a registered authentication realm from the list of HTTP realms that are administered by the HTTP daemon. The HTTP daemon must be restarted before the realm is actually deleted.
Authorization
senior, super
Arguments
–d RealmDir Specifies the realm directory relative to the Common Gateway Interface (CGI) base directory.
EXAMPLESThe following example removes the authentication realm /cgi-bin/MyDir from the HTTP daemon’s list of authentication realms:wdelrealm –d /cgi-bin/MyDir
SEE ALSOwcrtpr, wlsrealms, wstarthttpd, wstophttpd
wdelsched
1–212 Version 3.7
wdelsched Removes jobs from the scheduler.
SYNOPSISwdelsched [–b ‘mm/dd/yyyy hh:mm’] [–a ‘mm/dd/yyyy hh:mm’]
wdelsched [–s id [–s id] …]
DESCRIPTIONThe wdelsched command removes jobs from the scheduler. If no options are specified, information on all jobs is removed. The –a and –b arguments are used to delimit jobs that fall within certain time ranges. The –s argument is used to specify jobs by their ID number.
Authorization
super, senior, admin
Arguments
–b ‘mm/dd/yyyy hh:mm’ Specifies jobs that are scheduled to execute before this time.
–a ‘mm/dd/yyyy hh:mm’ Specifies jobs that are scheduled to execute after this time.
–s id… Specifies the job ID.
EXAMPLES
1. The following example deletes all jobs scheduled to run before May 6, 1998 at 1:00 a.m. and after May 8, 1998 at 1:00 p.m.:
wdelsched –b '05/06/1998 01:00' –a '05/08/1998 13:00'
2. The following example deletes job IDs 876 and 934:
wdelsched –s 876 –s 934
SEE ALSOwschedjob, wenblsched, wgetsched, wedsched, wstartsched
wdeltask
Tivoli Management Framework Reference Manual 1–213
Com
mands
wdeltask Deletes a task from a task library.
SYNOPSISwdeltask task_name lib_name
DESCRIPTIONThe wdeltask command deletes a task from a task library.
Authorization
admin, senior, super
Argument
task_name Specifies the name of the task to be deleted.
lib_name Specifies the name of the task library where the task resides.
EXAMPLESThe following example deletes task date_task from task library my_tasks. wdeltask date_task my_tasks
SEE ALSOwcrttask, wdeljob
wdepot
1–214 Version 3.7
wdepotManages MDist 2 repeater depots.
SYNOPSISwdepot repeater_name add segment_spec [src_host:]pathname
wdepot repeater_name delete filter
wdepot repeater_name describe
wdepot repeater_name list [filter] [–l]
wdepot repeater_name purge
DESCRIPTIONThe wdepot command manages MDist 2 repeater depots. The wdepot command provides the ability to add segments to depots, list existing depots, delete depot entries, purge depot entries, and display depot configuration information.
Authorization
The add, delete, and purge arguments require the admin authorization role. The describe and list arguments require any Tivoli authorization role.
Add Arguments
add Adds an entry to the depot with the specified segment.
pathname Specifies the complete path and file name of the source file. On Windows NT, if the path name contains a drive letter (for example, C:\), the src_host argument must be specified.
repeater_name Specifies the label, object ID, or managed node ID of a repeater.
segment_spec Specifies the ID and the version of the segment. segment_spec must be a double-quoted string with ID and version separated by a ^ symbol if it contains spaces. The following is an example:
"Tivoli^3.7 "
wdepot
Tivoli Management Framework Reference Manual 1–215
Com
mands
src_host Specifies the host name for the source file. If not specified, it defaults to the local host.
List Arguments
list Lists all entries in the depot.
–l If present, the –l argument lists all information for each entry. Otherwise, the list argument lists the following information only: ID, version, size, percentage completed, and last modification time.
filter Specifies the entries to be listed. It uses the same format as the segment_spec argument, and it supports wildcards, such as the asterisk sign “*”. If no filter is specified, the wdepot list command lists all entries in the depot.
Delete Arguments
delete Deletes entries specified by the filter that are not currently locked by distributions in the repeater’s queue. Before deletion, the wdepot delete command prompts the user for confirmation.
Purge Arguments
purge Deletes all entries in the depot, excluding active distributions. The user is prompted for confirmation before the depot is purged. To delete active distributions in a repeater’s queue, see the wmdist command.
Describe Arguments
describe Displays configuration of the depot. Configuration parameters include location, size, temporary storage, permanent storage, total storage, and free space. These parameters can be changed with the wmdist command.
wdepot
1–216 Version 3.7
EXAMPLES
1. The following example adds an entry with ID Tivoli and version 3.7 to the depot of repeater banshee. The source host is seesaw, and the path name is /data/file:
wdepot banshee add "Tivoli^3.7" -f seesaw:/data/file
2. The following example list all entries starting with character T in the depot of repeater banshee:
wdepot banshee list "T*"
3. The following example deletes entries starting with character T from the depot of repeater banshee:
wdepot banshee delete "T*"
4. The following example displays the configuration of the depot of repeater banshee:
wdepot banshee describe
SEE ALSOwmdist
wdisconn
Tivoli Management Framework Reference Manual 1–217
Com
mands
wdisconn Disconnects two Tivoli Management Regions (TMRs).
SYNOPSISwdisconn [–s] TMR_name
wdisconn [–s] –r region
DESCRIPTIONThe wdisconn command disconnects two TMRs. Disconnecting TMRs after they have exchanged resources is a time-consuming process and should be done with care. To ensure database consistency, you should always run wchkdb after disconnecting TMRs.
Authorization
super
Arguments
–s Specifies that the connection to be broken is a single-sided connection. Do not attempt to connect the other TMR server. You might use this argument if you inadvertently specified both ends of a one-way connection as the managing server or if you specified the same region number for both ends of a connection. This argument disconnects one end of the connection without impacting the other end. You can then reconnect the TMR using the correct information.
TMR_name The name of the remote TMR. The name of a TMR is the same as that of the initial policy region created when the server was installed.
–r region The number of the remote TMR. This argument is required if the TMR name is not available.
EXAMPLES
1. The following example disconnects region number 4000447345 from the local TMR.
wdisconn –r 4000447345
wdisconn
1–218 Version 3.7
2. The following example disconnects the TMR writers-Region from the local TMR. Only the writers-Region TMR will be disconnected.
wdisconn –s writers-Region
SEE ALSOwchkdb, wconnect, wlsconn, wupdate
wdiskspace
Tivoli Management Framework Reference Manual 1–219
Com
mands
wdiskspace Prints the number of free kilobytes available in the specified directory (file system) of the specified managed node.
SYNOPSISwdiskspace hostname directory
DESCRIPTIONThe wdiskspace command prints the amount of free disk space in kilobytes in the specified directory (file system) of the specified managed node.
Authorization
user, admin, senior, super
Arguments
hostname The managed node on which to check for free disk space.
directory The directory in which to check for free disk space. The directory must be specified as an absolute path.
EXAMPLESThe following example shows the available disk space in the /tmp directory on managed node bald: wdiskspace bald /tmp11747
SEE ALSOwdate, whostid, wifconfig, winterp, wmannode, wmemsize, wping, wtimezone, wuname, wxterm
wdistrib
1–220 Version 3.7
wdistrib Distributes one or more profile copies.
SYNOPSISwdistrib [–l maintain | over_all | over_opts | over_all_no_merge] [–m] [–r] name [subscriber…]
DESCRIPTIONThe wdistrib command distributes one or more copies of a profile to its profile manager’s subscribers. The command updates subscriber databases and configuration files from the Tivoli database. The name argument specifies the profile to distribute or the profile manager from which all profiles will be distributed. The subscribers to distribute to are specified in subscriber. If no subscribers are specified, wdistrib updates all subscribers.
If the –m argument is specified, profiles are distributed to all levels of subscribers. If –m is not specified, profiles are distributed to only the next level of subscribers.
The –l argument identifies the distribution level. If –l is not specified, the default is maintain.
Authorization
admin, senior, super
Arguments
–l maintain | over_all | over_opts | over_all_no_merge Specifies the distribution level. The maintain argument keeps local modifications. The over_all argument overwrites local modifications. The over_opts argument merges and distributes all records. The over_all_no_merge option distributes only the specified profile.
–m Specifies a multistep distribution.
–r Sets the return code to 1 if at least one profile distribution or retrieval to or from a profile manager fails.
wdistrib
Tivoli Management Framework Reference Manual 1–221
Com
mands
name The name of the profile to be distributed or the profile manager from which all profiles will be distributed. Valid formats for the name argument include:
■ @ProfileType:prof_name
■ /Regions/PolicyRegionName/prof_manager_name/prof_name
subscriber… The names of the Tivoli resources to which to distribute a profile copy. Valid formats for the subscriber argument include:
■ @ManagedNode:node_name
■ /Regions/PolicyRegionName/prof_manager_name
EXAMPLES
1. The following example distributes profiles contained in the Development profile manager to all subscribers of that profile manager. Any local modifications to this profile will be maintained.
wdistrib /Regions/Development
2. The following example distributes the Admin user profile to subscribers pinatubo, rushmore, and to profile manager Marketing. The profile will not be distributed to subscribers of Marketing. All local changes will be overwritten by this distribution.
wdistrib –l over_all @UserProfile:Admin pinatubo \rushmore @ProfileManager:Marketing
3. The following example distributes the Admin user profile to the subscribing profile manager Sales. The profile will be further distributed to endpoints or profile managers that subscribe to Sales.
wdistrib –m @UserProfile:Admin @ProfileManager:Sales
SEE ALSOwcrtprf, wcrtprfmgr, wgetsub, wlssub, wpopulate, wgetprf, wsub, wunsub, wvalidate
wdisttask
1–222 Version 3.7
wdisttaskControls the distribution of task binaries for a task library.
SYNOPSISwdisttask –q library_name
wdisttask –s library_name mode
wdisttask –d library_name task_name
DESCRIPTIONThe wdisttask command can query or set the distribution mode of a task library or can force a distribution of the binaries for a task to occur.
Task binaries can remain on the Tivoli Management Region (TMR) server of the local TMR (ALI mode), be distributed to all file servers in the local TMR (LOCAL mode), or be distributed to all file servers in every connected TMR (GLOBAL mode). You should use the GLOBAL distribution mode only when a Tivoli-based application requires that the task binaries reside on a local file system. A global distribution is a resource-intensive operation that temporarily slows down your network.
Arguments
–d Forces the distribution of task binaries to occur immediately.
–q Determines the distribution mode of a task library.
–s Sets the distribution mode of a task library.
library_name Specifies a task library.
mode Specifies the mode to be used to distribute a task library. The mode can be one of the following:
ALI Specifies that the task binaries be stored only on the TMR server for the local TMR.
LOCAL Distributes copies of the task binaries to every file server in the local TMR.
wdisttask
Tivoli Management Framework Reference Manual 1–223
Com
mands
GLOBAL Distributes copies of the task binaries to every file server in every connected TMR.
If you perform a global distribution to two or more TMRs that share the same file server, the distribution fails.
task_name Specifies the task binaries to be distributed.
EXAMPLES
1. The following example queries the distribution mode of the task library named abc:
wdisttask –q abcGLOBAL
2. The following example changes the distribution mode of the task library named abc to distribute task binaries to the file servers of the local TMR only:
wdisttask –s abc LOCAL
3. The following example immediately distributes the binaries for the task named rm_core_files in the abc task library:
wdisttask –d abc rm_core_files
SEE ALSOwcrttask, wgettask
wdskspc
1–224 Version 3.7
wdskspcVerifies the amount of disk space available. This command should be run from an endpoint. (Windows and NetWare)
SYNOPSISwdskspc [–q] [–f output_file] [–s required_size] volume_label
DESCRIPTIONThe wdskspc command returns the amount of available disk space on the specified volume. If you specify the –s argument, the command sets the return code of the command to zero if the required disk space is available and to nonzero if not available. If you do not specify the –s argument, the wdskspc command displays the total available disk space.
The wdskspc command detects and displays up to 2 GB on Windows 95 platforms. The wdskspc command proceeds uninterrupted if it detects more available space.
Arguments
–f output_file Redirects any information or errors to the specified output file.
–q Limits the information returned to the required or available disk space depending whether the –s argument is specified.
–s required_size Specifies the amount of disk space required. The required_size argument can have any of the following suffixes:
k: kilobytesm: megabytesg: gigabytes
The total amount of available disk space is not displayed with this option.
volume_label Returns the amount of available disk space on the volume or disk for the specified volume or disk.
wdskspc
Tivoli Management Framework Reference Manual 1–225
Com
mands
RETURNS
wdskspc returns one of the following when used with the –s argument:
0 Indicates that wdskspc was successful in identifying that the specified amount of disk space is available.
nonzero Indicates that the required disk space is not available.
EXAMPLES
1. To check drive C for 10 MB of available disk space, enter the following command:
wdskspc –s 10m C:\
2. To check the total disk space available on drive C, enter the following command:
wdskspc C:\
3. To check the SYS volume for 20 MB of available disk space on a NetWare machine, enter the following command:
wdskspc –s 20m SYS:
weditini
1–226 Version 3.7
weditiniModifies the groups, variables, and values in an .INI file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISweditini [–r] –g section_name [–n variable_name] [–v value] filename
DESCRIPTIONThe weditini command edits the contents of an .INI file. Using this command, you can add a variable and value to a section of the file, remove a variable or section, or replace the value of a specified variable.
Arguments
–g section_name Specifies the name of the section in the .INI file to process. If you add a variable to a section that does not exist, the section is created and the variable is added.
–n variable_name Specifies the variable name to add, replace, or remove.
–r Removes the specified section or variable.
–v value Specifies the value to add or replace for the variable specified by the –n argument.
filename Specifies the full path of the file to edit.
RETURNSweditini returns one of the following:
0 Indicates that weditini successfully edited the .INI file.
nonzero Indicates that weditini did not successfully edit the .INI file.
weditini
Tivoli Management Framework Reference Manual 1–227
Com
mands
EXAMPLES
1. To add the DefaultDirectory variable to the UserSettings section in the C:\WINDOWS\SYSTEM.INI file and set its value to C:\WORK, enter the following command:
weditini –g UserSettings –n DefaultDirectory –v C:\WORK \C:\WINDOWS\SYSTEM.INI
2. To remove the group UserSettings from the C:\WINDOWS\SYSTEM.INI file, enter the following command:
weditini –r –g UserSettings C:\WINDOWS\SYSTEM.INI
SEE ALSOwmrgini
wedsched
1–228 Version 3.7
wedsched Edits a job that currently exists in the scheduler.
SYNOPSISwedsched [–c ‘time_period’ | OFF] [ –C {daytime | nighttime | weekday | weekend} {from to | OFF}][–D] [–d desktop… | OFF][–f file | OFF –h host] [–g group | OFF] [–m email | OFF][–l label] [–o] [–R ‘time_period’ | ‘iterations’ | OFF] [–r ‘time_period’ | ‘iterations’ | OFF] [–t ‘mm/dd/yyyy hh:mm’] id
DESCRIPTIONThe wedsched command allows administrators to edit a job that currently exists in the scheduler. Administrators must know the ID of the job to edit. This can be found by using the wgetsched command.
Authorization
super, senior, admin
Arguments
–c Specifies when a job will be canceled. Valid arguments are as follows:
‘time_period’ Specifies when a job will be canceled if it did not start as scheduled. You must specify a number (amount of time) and a unit of time. The unit of time must be minute, hour, or day. For example, if you specify ’3 hour’, the job will be canceled three hours after its originally scheduled start time if it has not already started.
OFF Turns off the cancellation feature. The job will not be canceled.
wedsched
Tivoli Management Framework Reference Manual 1–229
Com
mands
–C Specifies the conditions or restrictions under which the job will run. The from argument can be either a starting day or a starting time. The to argument can be either an ending day or an ending time. Times must be entered using a 24-hour clock (for example, 9:00 for 9 a.m. or 14:00 for 2 p.m.). Days must be entered as numeric values where Sunday is 0 and Saturday is 6. Valid arguments are as follows:
daytime from to | OFF Specifies the job will run only during the day. Specifying the OFF option removes this restriction.
nighttime from to | OFF Specifies the job will run only at night. Specifying the OFF option removes this restriction.
weekday from to | OFF Specifies the job will run only during the week. Specifying the OFF option removes this restriction.
weekend from to | OFF Specifies the job will run only on weekends. Specifying the OFF option removes this restriction.
–D Disables the job. The job remains in the scheduler but will not be run until it is enabled.
–d Specifies whether a Status dialog will be displayed on a desktop when any action is performed on the job. Valid arguments are as follows:
desktop… Specifies which desktop will display the Status dialog when any action is performed on the job. Multiple desktops can be specified.
wedsched
1–230 Version 3.7
OFF Specifies that the Status dialog will not be displayed when any action is performed on the job.
–f Specifies whether the job status will be written to file when any action is performed on the job. Valid arguments are as follows:
file Specifies the file to which the job status will be written when any action is performed on the job. If a file is specified, the –h argument must be used to specify a host on which the file is to be written.
OFF Specifies that the job status will not be written to a file.
–g Specifies whether the job status will be sent to a Tivoli notice group when any action is performed on the job. Valid arguments are the following:
group Specifies the notice group to which the job status will be sent when any action is performed on the job. Multiple notice groups can be specified.
OFF Specifies that the job status will not be sent to a notice group.
–h host Specifies the host on which the job status file is to be written. Must be used with the –f argument.
–l label Specifies the name specific to this instance of the job.
–m Specifies whether the job status will be sent to an e-mail address when any action is performed on the job. Valid arguments are as follows:
email Specifies the e-mail address to which the job status will be sent when any action is performed on the job. Multiple e-mail addresses can be specified.
wedsched
Tivoli Management Framework Reference Manual 1–231
Com
mands
OFF Specifies that the job status will not be sent to an e-mail address.
–o Specifies that the time indicated in the –t argument is in the past. Overrides the warning message.
–R Specifies the retry information. If the iterations argument is specified, the job will retry for a finite number of times. One of the following arguments must be specified:
‘time_period’ Specifies how often a job will be retried. You must specify a number (amount of time) and a unit of time. The unit of time must be minute, hour, or day. For example, if you specify 3 hour, the job will be retried every three hours until it completes successfully.
‘iterations’ Specifies how many times a job will be retried. You must specify an amount of time, a unit of time, and a number of times to retry. The unit of time must be minute, hour, or day. For example, if you specify ’3 hour 6’, the job will be retried every three hours until it has been retried six times.
OFF Turns off the retry feature. The job will not be retried if it fails to complete successfully.
–r Specifies the repeat information. If the iterations argument is specified, the job will repeat for a finite number of times. One of the following arguments must be specified:
‘time_period’ Specifies how often a job will be repeated. You must specify a number (amount of time) and a unit of time. The unit of time must be minute, hour, day, week, month, or year. For
wedsched
1–232 Version 3.7
example, if you specify ’3 hour’, the job will be repeated every three hours.
‘iterations’ Specifies how many times a job will be repeated. You must specify an amount of time, a unit of time, and a number of times to repeat. The unit of time must be minute, hour, day, week, month, or year. For example, if you specify ’3 hour 6’, the job will be repeated every three hours until it has been repeated six times.
OFF Turns off the repeat feature. The job will not be repeated.
–t ‘mm/dd/yyyy hh:mm’ Specifies the time the job is scheduled to initially execute. You can enter the date and time in either order. You can also enter only the date or only the time. If you enter the time without a date, the job will execute at the specified time on the current date. If you enter the date without a time, the job will execute at the current time on the specified date. Times must be entered using a 24-hour clock (for example, 9:00 for 9 a.m. or 14:00 for 2 p.m.).
id Specifies the job ID.
EXAMPLES
1. The following example changes the start time of job 782 to 6:00 p.m., November 30, 1998. (Use the wgetsched command to find the job ID.)
wedsched –t '18:00 11/30/1998' 782
wedsched
Tivoli Management Framework Reference Manual 1–233
Com
mands
2. The following example edits job 35. The example turns off the cancellation feature and sets the retry for one day after each failure. The job status will not be written to a file, but will be sent to the Tivoli Diagnostics notice group.
wedsched –c OFF –R '1 day' –f OFF \–g 'Tivoli Diagnostics' 35
3. The following example edits job 728 to run every Monday through Friday.
wedsched –r '1 day' –C 'weekday 1 5' 728
4. The following example changes the restrictions on job 28 from weekends (Saturday and Sunday) to weekdays (Monday through Friday).
wedsched –C 'weekend OFF' –C 'weekdays 1 5' 28
SEE ALSOwdelsched, wenblsched, wgetsched, wschedjob, wstartsched
wenblsched
1–234 Version 3.7
wenblsched Disables or enables scheduled jobs.
SYNOPSISwenblsched [–b ‘mm/dd/yyyy hh:mm’] [–a ‘mm/dd/yyyy hh:mm’] [–d]
wenblsched [–s id [–s id] …] [–d]
DESCRIPTIONThe wenblsched command allows an administrator to disable or enable scheduled jobs. When a job is disabled it will not execute. If no arguments are specified, all jobs are enabled or disabled. The –a and –b arguments are used to delimit jobs that fall within certain time ranges. The –s argument is used to specify jobs by their ID number. The –d argument is used to disable scheduled jobs.
Authorization
admin, senior, super
Arguments
–b ‘mm/dd/yyyy hh:mm’ Specifies jobs that are scheduled to execute before this time.
–a ‘mm/dd/yyyy hh:mm’ Specifies jobs that are scheduled to execute after this time.
–s id… Specifies the job ID. You can specify more than one ID.
–d Specifies to disable jobs.
EXAMPLES
1. The following example enables all jobs scheduled to run before May 6, 1998, at 1:00 a.m. and after May 8, 1998, at 1:00 p.m.
wenblsched –b '05/06/1998 01:00' –a '05/08/1998 13:00'
2. The following example disables job IDs 529 and 734:
wenblsched –s 529 –s 734 –d
wenblsched
Tivoli Management Framework Reference Manual 1–235
Com
mands
SEE ALSOwdelsched, wgetsched, wschedjob, wedsched, wstartsched
wep
1–236 Version 3.7
wep Performs actions on endpoint information contained in the endpoint list.
SYNOPSISwep
wep ep_label
wep del ep_oid gw_label
wep ep_label get {httpd | id | gateway | netload | address | policy}
wep ls [–g gw_label]
wep ep_label migrate [–f] gw_label
wep ep_label set_label new_label
wep ep_label set httpd value
wep set address ep_address
wep set gateway {–g gw_label | –e ep_label}
wep set interfaces {–g gw_label | –e ep_label} gw_label+port [:gw_label+port]…
wep ep_label set_label new_label
wep ep_label status
wep ep_label upgrade disable|enable
wep sync_gateways
wep view ep_oid gw_label…
wep boot_method add tag prototype_object method_name ep_oid…
wep boot_method list tag ep_oid
wep boot_method remove tag ep_oid…
wep boot_method test tag ep_oid
wep
Tivoli Management Framework Reference Manual 1–237
Com
mands
DESCRIPTIONThe wep command performs actions on the endpoint information contained in the endpoint list maintained by the endpoint manager. Using this command, you can list the endpoints in a Tivoli Management Region (TMR) and their assigned gateway, retrieve and set endpoint information, migrate an endpoint from one gateway to another, or update any endpoint data changes within a TMR. When you perform the wep command without arguments, it displays the usage statement for wep.
To view the Hypertext Transfer Protocol (HTTP) password, you must have the admin role in the endpoint’s policy region.
Authorization
To view endpoint information with the wep ep_label, wep ep_label get, wep ls commands: user, admin, senior, or super
To set the HTTP password, set an endpoint’s gateway, or view status with the wep ep_label set httpd, wep set interfaces –e, wep status commands: senior or super in the endpoint’s policy region
To migrate an endpoint, view status, set all endpoints’ gateways, or synchronize endpoint data with the wep migrate, wep status, wep set interfaces –g, wep set gateway, wep sync_gateways commands: senior or super in the TMR
Arguments
ep_label Identifies the endpoint on which other wep subcommands will be executed. Without other subcommands, wep ep_label lists the information contained in the endpoint list for the specified endpoint.
get {httpd | id | gateway | netload | address | policy} Retrieves the following information from the endpoint list for a specified endpoint:
httpd Gets the HTTP password. The HTTP password is used to modify endpoint information through a Web browser.
id Gets the unique ID.
wep
1–238 Version 3.7
gateway Gets the assigned gateway.
netload Gets the current netload setting.
address Gets the network address (Internet Protocol [IP] address and port number).
policy Gets the policy region in which the endpoint resides. If you have not added the endpoint to a policy region, the results of this command will be OBJECT_NIL.
ls [–g gw_label] Lists each gateway in a TMR and its assigned endpoints. If the –g gw_label is used, only the specified gateway and its endpoints are listed.
migrate [–f] gw_label Migrates an endpoint from its assigned gateway to the gateway specified by gw_label. The association of the endpoint to its assigned gateway is updated at the gateway level. No endpoint action is required. Communication between the endpoint and its new gateway is established with the next upcall, downcall, or endpoint login. Specifying the –f argument forces the migration of an endpoint even if the gateway’s status could not be retrieved.
set address ep_address Changes the IP address of an endpoint.
set gateway {–g gw_label | –e ep_label} Prompts a gateway to send its network information to its assigned endpoints. Use the –g argument to invoke this command on all the endpoints assigned to the gateway specified by gw_label. Use the –e argument to invoke this command on the endpoint specified by ep_label.
wep
Tivoli Management Framework Reference Manual 1–239
Com
mands
set httpd value Sets the HTTP password for the specified endpoint. The HTTP password is used to modify endpoint information through a Web browser. You must use the sync_gateways argument to synchronize changes between the endpoint, gateway, and endpoint manager after making password changes.
set interfaces {–g gw_label | –e ep_label} gw_label+port [:gw_label+port]…
Sets the address and port of one or more gateways to which an endpoint can log in. Use the –g argument to invoke this command on all the endpoints assigned to the gateway specified by gw_label. Use the –e argument to invoke this command on the endpoint specified by ep_label. You can specify more than one gateway address. Multiple addresses must be separated by colons.
set_label new_label Changes the current label (ep_label) of an endpoint to a new label specified by new_label.
status Lists the status of the specified endpoint. An endpoint’s status consists of either “alive” or “endpoint may be unreachable” if the status could not be determined.
sync_gateways Synchronizes the endpoint data stored by the endpoint manager, gateways, and endpoints within a TMR. If you make changes to an endpoint’s HTTP password or policy region or decide to use one of the advanced commands in the following section, you must use this option for updates to take effect. This option is useful as part of a batch file that uses the job scheduler function to schedule several endpoint data updates at once.
Note: To change the policy region of an endpoint, use the wmv command.
upgrade disable|enable Specifies whether the endpoint is upgradable or not.
wep
1–240 Version 3.7
Advanced Commands
If you are not explicitly familiar with the advanced implications of the wep command, call your Customer Support provider before attempting to perform any of the following wep operations:
wep del ep_oid gw_label Deletes the endpoint from an epmgr.bdb file. Because there are separate .bdb files for each gateway, it is necessary to specify the endpoint’s assigned gateway. The gw_label can be found by issuing the wep ls command. The wep del command does not completely delete all references to the endpoint.
view ep_oid gw_label Displays endpoint information stored in the .bdb file associated with the gateway and located in the $DBDIR/epmgr.bdb directory. Unlike the wep ep_label command, the wep view command does not search the endpoint manager’s internal cache. The gw_label can be found by issuing the wep ls command.
The following advanced commands are used to configure boot methods created by application developers (using Application Development Environment [ADE]) to run on an endpoint. You can use these options to configure boot methods during the installation of an endpoint or during the distribution of application profiles. These methods will run every time an endpoint logs in to a gateway.
boot_method add tag prototype_object method_name ep_oid… Adds the specified boot method to the endpoint, where
tag Specifies the user specified name.
prototype_object Specifies the prototype object’s identification number, which implements the method.
method_name Specifies the name of the method.
wep
Tivoli Management Framework Reference Manual 1–241
Com
mands
ep_oid… Specifies the object identification number (OID) of one of several endpoints on which the method will run. Separate OIDs with spaces.
boot_method list tag ep_oid Lists the prototype object number and method name of the specified boot method on the endpoint.
boot_method remove tag ep_oid… Removes the specified boot method from the endpoint.
boot_method test tag ep_oid Starts the specified boot method on the endpoint.
EXAMPLES
1. The following example lists the endpoints assigned to the jadams-gateway:
wep ls -g jadams-gateway
1122334455.1.512 jadams-gateway1122334455.10.500+ cookU1122334455.11.500+ cookA1122334455.12.500+ jadams1122334455.13.500+ jadamsM1122334455.15.500+ jadamsG
2. The following example returns all information contained in the endpoint list regarding endpoint cookG:
wep cookG
object 1122334455.9.500+label cookG
id 2155793934gateway 1122334455.1.512#TMF_Gateway::Gateway#netload OBJECT_NIL
crypt 0interp solaris2
address 146.84.26.26+9494policy OBJECT_NILhttpd tivoli:WBHtK’y3alias OBJECT_NIL
wep
1–242 Version 3.7
3. The following example returns the network address of endpoint cookG:
wep cookG get address146.84.26.26+9494
4. The following example returns the randomly generated HTTP password for endpoint cookG:
wep cookG get httpdtivoli:WBHtK’y3
where:
tivoli Represents the user name
: Is the separator
wBHtK’y3 Represents the password
5. The following example returns the prototype object and method name of the test18 boot method on endpoint 1802218143.13.500:
wep boot_method list test18 1802218143.13.500+
Boot Method(s) for Endpoint 1802218143.13.500+TagPrototype ObjectMethod Nametest181802218143.13.500admin
SEE ALSO
wmv
wepmgr
Tivoli Management Framework Reference Manual 1–243
Com
mands
wepmgrProvides control and configuration for the endpoint manager.
SYNOPSISwepmgr [fsck | get | help | ping | restart | start | stop | update | set attribute value | set login_address]
DESCRIPTIONThe wepmgr command provides control and configuration for the endpoint manager. With this command, you can start, stop, and restart the endpoint manager. In addition, this command gets and sets endpoint manager attributes in the Tivoli object database to control endpoint login.
Authorization
senior, super
Arguments
fsck Rewrites the data in the Tivoli name registry endpoint resource from the endpoint data in the endpoint manager.
get Displays the endpoint manager object attributes from the Tivoli object database.
help Displays the usage statement for wepmgr.
ping Verifies that the endpoint manager is running.
restart Restarts the endpoint manager.
set attribute value Sets the endpoint manager object attributes in the Tivoli object database. Use the get argument for a list of attributes. You will need to use the update argument for these attributes to take immediate effect.
wepmgr
1–244 Version 3.7
set login_interval Specifies the interval in which logins from the same endpoint will be ignored. This interval prevents the duplication effects of multiple initial logins from the same endpoint. The default value is 270 seconds. You must restart all gateways for the new setting to take effect.
start Starts the endpoint manager.
stop Stops the endpoint manager.
update Refreshes the attributes in the running endpoint manager from the attributes on the endpoint manager object in the Tivoli object database.
EXAMPLES
1. The following example sends a ping to the endpoint manager to verify that it is up and running:
wepmgr ping
2. The following example sets the endpoint manager login_interval attribute to 300 seconds on the endpoint manager object in the Tivoli object database. The following command then updates the endpoint manager so that the attribute setting will take effect on the running endpoint manager.
wepmgr set login_interval 300wepmgr update
wexpnotif
Tivoli Management Framework Reference Manual 1–245
Com
mands
wexpnotif Expires notices from a notice group.
SYNOPSISwexpnotif [–a age] ngroup
DESCRIPTIONThe wexpnotif command expires notices from a notice group. Notice groups normally have an associated expiration time. This command can be used to force the expiration of notices before their normal expiration time. If the –a argument is specified, only notices older than the specified age are expired. If the –a argument is not specified, this command expires all notices in the specified notice group immediately.
Authorization
You must have at least the senior role in the Tivoli Management Region (TMR).
Arguments
–a age Specifies that only notices older than age are to be expired. age is specified in hours. If this option is not specified, all notices in the specified notice group are expired immediately.
ngroup The notice group for which notices are to be expired.
EXAMPLESThe following example specifies that all Tivoli Administration notices should be expired after three hours: wexpnotif -a 3 "Tivoli Administration"
SEE ALSOwlsnotif, wsndnotif, wtailnotif
wgateway
1–246 Version 3.7
wgatewayStarts, stops, or lists the properties of an endpoint gateway.
SYNOPSISwgateway
wgateway gateway_name {describe | start | stop | restart | dbcheck}
wgateway gateway_name add_gatewayproxy managednode_name
wgateway gateway_name get_gatewayproxies
wgateway gateway_name remove_gatewayproxy managednode_name
wgateway gateway_name reset_gatewayproxies
wgateway gateway_name set_debug_level level
wgateway gateway_name set_session_timeout seconds
wgateway gateway_name [add_protocol protocol] [rm_protocol protocol] [set_protocols protocol_list] [set_ipx_port port] [set_tcp_port port]
DESCRIPTIONThe wgateway command starts a gateway, stops a gateway, or lists the properties of the specified gateway. You can run wgateway to list gateway object identification numbers, names, and status within a Tivoli Management Region (TMR), as follows:wgateway
Object Name Status2002780303.1.524 tinman-gateway u
Status values include:
u The gateway is running and responding to requests.
d The gateway is not running.
D A communications error occurred. The object dispatcher is down and possibly the machine as well.
Authorization
senior
wgateway
Tivoli Management Framework Reference Manual 1–247
Com
mands
Argument
gateway_name Identifies the name of the gateway.
add_protocol TCPIP|IPX Adds a supported protocol for the specified gateway. Supported protocols are Transmission Control Protocol/Internet Protocol (TCP/IP) (the default) and Internetwork Packet Exchange (IPX).
add_gatewayproxy Adds a managed node as an entry to the gateway proxies list.
dbcheck Synchronizes the gateway’s method cache with that on the TMR server.
describe Lists the properties of the specified gateway. This is the default option.
get_gatewayproxies Displays the list of gateway proxy objects that have been added to the named gateway.
remove_gatewayproxy Removes a managed node as an entry from the gateway proxies list.
reset_gatewayproxies Clears the gateway proxies list.
restart Stops and restarts the specified gateway.
rm_protocol IPX Removes a supported protocol for the specified gateway. The TCP/IP protocol cannot be removed.
set_debug_level level Determines the level (0 through 8) of message information logged by the gateway. Levels include the following:
0 Errors. This is the default and recommended level.
1 Errors and warnings.
wgateway
1–248 Version 3.7
2 Harmless exceptions.
3 Verbose communication information.
5 Verbose boot, database check, and endpoint login information.
6 Verbose upcall, downcall, and repeater information.
7 Verbose job scheduler information.
8 Verbose gateway cache information.
Note: Level 4 does not exist.
set_ipx_port port Sets the port number on which the specified gateway listens for IPX packets. The default port number is 9494, but you should set your own value.
set_protocols protocol_list Sets a supported protocol for the specified gateway. TCP/IP is the default.
set_session_timeout seconds Determines the amount of time (in seconds) a gateway will wait for a response from an endpoint after sending a downcall. The default is 300 seconds (five minutes).
set_tcp_port port Sets the port number on which the specified gateway listens for TCP/IP packets. The default port number is 9494, but you should set your own value.
start Starts the specified gateway. The oservrun command starts the object dispatcher from the NetWare Console.
stop Stops the specified gateway. The oservend command stops the object dispatcher from the NetWare Console.
wgateway
Tivoli Management Framework Reference Manual 1–249
Com
mands
EXAMPLESThe following example shows the results of the wgateway command when the gateway uses IPX and TCP/IP.wgateway lux describe
Object : 1139479731.2.77#TMF_Gateway::Gateway#Protocols : TCPIP,IPXHostname : "lux"TCPIP Port : 9999IPX Port : 7787Timeout : 300
The following example shows the results of the wgateway command when the gateway uses TCP/IP.wgateway agodino-gateway describe
Object : 1139479731.1.644#TMF_Gateway::Gateway#Protocols : TCPIPHostname : "agodino"TCPIP Port : 6666Timeout : 300
The following example shows the gateway proxy list of the NetWare gateway lux.wgateway lux add_gatewayproxy agodino
The following example shows the gateway proxy list of the NetWare gateway lux.wgateway lux get_gatewayproxies113947931.1.530
wgetadmin
1–250 Version 3.7
wgetadmin Lists information about a Tivoli administrator.
SYNOPSISwgetadmin [–n | –o | –p | -u [-i interp]] [name]
DESCRIPTIONThe wgetadmin command lists information about a Tivoli administrator to standard output. This command lists the administrator’s name, logins, roles, and notice groups. The administrator’s roles are listed by groups. If name is not specified, wgetadmin lists the information of the current administrator.
Authorization
You must have at least the user role to list information about another administrator. Otherwise, you can only list the information about the current administrator.
Argument
–n Displays only the name of the administrator.
–o Displays only the object ID of the administrator.
–p Displays extended output.
-u Displays the User Login Name and the Group Name of the administrator.
i interp Resolves the User Login Name and Group Name of the administrator using the interpreter specified in interp.
name Specifies the name of the Tivoli administrator whose properties to list.
EXAMPLES
1. The following example displays information about the administrator currently logged in:
wgetadmin
wgetadmin
Tivoli Management Framework Reference Manual 1–251
Com
mands
2. The following example displays information about the specified administrator:
wgetadmin callahan@sthelensAdministrator Steve Callahanlogins: callahan@sthelensroles: global user
DefaultRegion super, admin, userAdministrators super, seniorMyRegion super, senior, admin, user, backupSteve Callahan admin, user, rconnectsecurity_group_any_admin user
notice groups: Tivoli Authorization
SEE ALSOwcrtadmin, wsetadmin
BUGSwgetadmin does not show the user name or group name associated with the administrator. You must do this from the desktop.
wgetallinst
1–252 Version 3.7
wgetallinst Displays all instances of a resource type.
SYNOPSISwgetallinst [–l] resource_type
DESCRIPTIONThe wgetallinst command displays all instances of a resource type. If the –l argument is included, this command displays the resource type in the format ‘label oid’.
wgetallinst is similar to the wlookup command. The difference is that wlookup displays only those resource types registered in the name registry. wgetallinst displays both registered and unregistered resource types, including resource types that are supersets of other resource types. For example, wgetallinst displays all instances of the ProfileEndpoint resource type, which includes instances of the ProfileManager, ManagedNode, and NisDomain resource types.
Arguments
–l Lists the instances in the format ‘label oid’.
resource_type Specifies the resource type of the instances to be displayed.
EXAMPLESThe following example displays all instances of the ProfileEndpoint resource type: wgetallinst -l ProfileEndpoint
SEE ALSOwlookup
wgetdfpol
Tivoli Management Framework Reference Manual 1–253
Com
mands
wgetdfpol Lists a default policy object.
SYNOPSISwgetdfpol [–d | –v] class
DESCRIPTIONThe wgetdfpol command lists the label of the default policy default or policy validation object for the resource with the specified label. When a resource is added to a policy region as a managed resource, it receives both a default policy validation object and a default policy default object. These defaults are predefined as part of the resource definition.
A policy default object generates default values when creating objects of a given resource type in a policy region. A policy validation object implements the checking of attribute values for the objects of a managed resource type in a policy region.
Authorization
senior or super
Arguments
–d Lists the label of the resource’s default policy default object. This argument is the default if –v is not specified.
–v Lists the label of the resource’s default policy validation object.
class Specifies the type of managed resource whose default policy object’s label is to be listed.
EXAMPLESThe following example returns the name of the default policy default object for the ProfileManager class. wgetdfpol -d ProfileManager
wgetdfpol
1–254 Version 3.7
SEE ALSOwcrtpr, wdelpr, wchkpol, wcrtpol, wdelpol, wgetpolm, wlspol, wlspolm, wputpolm
wgeteppol
Tivoli Management Framework Reference Manual 1–255
Com
mands
wgeteppolLists the body and constant values of an endpoint policy script.
SYNOPSISwgeteppol pol_name
DESCRIPTIONThe wgeteppol command lists the contents of the specified endpoint policy script. You can modify the script to meet the needs of your organization. The endpoint policy scripts are allow_install_policy, after_install_policy, login_policy, and select_gateway_policy. For more information, see “Endpoint Policy” on page 2-6.
If you have not added an endpoint policy script yet, the output of wgeteppol will be the shell of a script as shown in “EXAMPLES.” Add the contents of the policy script after the comments and before the exit statement. Then use the wputeppol command to write the new script to disk.
Arguments
pol_name Specifies the name of the policy script to be returned.
Authorization
senior
EXAMPLESThe following example returns the after_install_policy script, which can then be modified as needed: wgeteppol after_install_policy#!/bin/sh## The following are the command line arguments passed to# this script from the Endpoint Manager.## $1 - The label of the endpoint machine# $2 - The object reference of the endpoint machine# $3 - The architecture type of the endpoint machine# $4 - The object reference of the gateway that the# endpoint logged into# $5 - The ip address of the endpoint logging in.
wgeteppol
1–256 Version 3.7
# $6 - Region# $7 - Dispatcher# $8 - Version# $9 - The inventory id of the endpoint logging in.#The following command line argument will be passed to this script #from the Endpoint Manager, when complied with the MULTIPROTO flag #turned on# $10 - The protocol of the endpoint logging in.#TCPIP -> TCP/IP#IPX -> IPX/SPX
#Note that the environment variable LCF_LOGIN_STATUS is also set by#the endpoint manager. A value of 2 indicates the endpoint#is isolated. That is, it was unable to contact its#assigned gateway. Isolated endpoints are automatically#migrated to another gateway unless the#select_gateway_policy terminates with a nonzero exit#status.##Also note that during the execution of #allow_install and select_gateway policy scripts,#the endpoint does not yet formally exist. For this#reason, the endpoint object reference will have a#value of OBJECT_NIL, and the object dispatcher number#will be 0. The endpoint label will have the value#suggested by the endpoint (or the user value lcfd -n),#but is not guaranteed to become the final endpoint #label. It will become the final endpoint label if#this value is not already taken by another endpoint.exit 0#
SEE ALSOwputeppol
wgetjob
Tivoli Management Framework Reference Manual 1–257
Com
mands
wgetjob Lists the properties of a job.
SYNOPSISwgetjob task_name library_name
DESCRIPTIONThe wgetjob command lists the properties of a job. The output of this command is sent to standard output.
Authorization
user, admin, senior, super
Arguments
task_name The name of the job to be listed.
library_name The name of the task library containing the specified job.
EXAMPLESThe following example lists the properties for the Clean Queue job:wgetjob "Clean Queue" queue_libJob Name : Clean QueueTask Name : Clean QueueExecution Mode : parallelTimeout : 60Output Format : task header
return codetask standard outputtask standard errordisplay output on desktop
Managed Nodes : yogi
Profile Managers :
SEE ALSOwcrtjob, wdeljob
wgetkey
1–258 Version 3.7
wgetkeyRetrieves the subkey listing in a registry hive. This command should be run from an endpoint. (Windows 95, Windows 98, and Windows NT only)
SYNOPSISwgetkey registry_key_path [registry_hive]
DESCRIPTIONThe wgetkey command retrieves the subkeys associated with the specified key path from the specified registry hive. The output of this command is returned to standard output (on the console).
Authorization
administrator
Arguments
registry_key_path Specifies a registry key name from which to retrieve the subkeys.
registry_hive Specifies the registry hive from which to retrieve the subkeys. Valid hives are as follows:
■ HKEY_LOCAL_MACHINE
■ HKEY_CLASSES_ROOT
■ HKEY_CURRENT_USER
■ HKEY_USERS
If you do not specify this argument, the command retrieves the subkeys from the HKEY_LOCAL_MACHINE registry hive.
wgetkey
Tivoli Management Framework Reference Manual 1–259
Com
mands
EXAMPLES
1. To retrieve the subkeys from the HKEY_LOCAL_MACHINE registry hive under the SOFTWARE key path, enter the following command. This command outputs a list of subkeys.
wgetkey SOFTWARE
2. To retrieve the key values from the HKEY_CURRENT_USER registry hive under the USERS key path, enter the following command:
wgetkey USERS HKEY_CURRENT_USER
wgetpolm
1–260 Version 3.7
wgetpolm Lists the body or constant value of a default or validation policy method.
SYNOPSISwgetpolm [–d | –v] class name policy
wgetpolm [–d | –v] profile policy
DESCRIPTIONThe wgetpolm command lists the body or constant value of a policy method to standard output. This command returns one of two things. If the policy method is implemented as a shell script (or executable program), this method returns the body of the script (or program). If the policy method is implemented as a constant value, it returns that constant value. This command does not explicitly indicate which way the method is implemented.
Note: For policy methods that are executable programs, this command returns the binary image of the executable program.
The –d argument (default) returns a default policy method, and –v returns a validation policy method. The class and name arguments specify the managed resource type and policy object name, respectively, while the policy argument specifies the individual attribute whose policy method to return, in the same form as the wlspolm command.
The second form of the command is used to query a policy from a profile. In this case, profile specifies the profile to query, and policy specifies the individual attribute whose policy to return, again as returned by the wlspolm command. If the policy is implemented as a constant value, this command returns that value. If the policy is implemented as a shell script (or executable program), it returns the script (or program) body to standard output, and prints the options to the script to standard error (see the wputpolm command). If the policy is undefined or specified as none, a message to that effect is printed to standard error and nothing is printed to standard output.
Authorization
You must have at least the senior role.
wgetpolm
Tivoli Management Framework Reference Manual 1–261
Com
mands
Arguments
–d Lists the specified policy default method. This action is the default if the –v argument is not specified.
–v Lists the specified policy validation method.
class Identifies the managed resource type whose policy is to be returned.
name Identifies the name of the policy object.
policy Identifies the attribute whose policy to return.
profile Identifies the profile whose policy to return.
EXAMPLESFor nonprofile usage:
This command returns the script body for the pm_val_subscribers method of the Restricted policy validation object for ProfileManager: wgetpolm -v "ProfileManager" "Restricted" \"pm_val_subscribers"
For profile usage:
The following example returns the script body for the default user ID (UID) policy for the user profile named Engineering. wgetpolm -d @UserProfile:Engineering uid
SEE ALSOwcrtpr, wdelpr, wchkpol, wcrtpol, wdelpol, wgetdfpol, wlspolm, wputpolm
wgetpr
1–262 Version 3.7
wgetpr Lists the properties of a policy region.
SYNOPSISwgetpr region
DESCRIPTIONThe wgetrp command lists the properties of a policy region.
Authorization
admin, senior, super
Arguments
region Specifies the target policy region.
EXAMPLESThe following example lists all of the managed resources in the DefaultRegion policy region: wgetpr @PolicyRegion:DefaultRegionTaskLibraryManagedNodeProfileManager
SEE ALSOwsetpr
wgetprf
Tivoli Management Framework Reference Manual 1–263
Com
mands
wgetprf Retrieves subscription copies of one or more profiles.
SYNOPSISwgetprf [–l maintain | over_all] [–m] [–r] name
DESCRIPTIONThe wgetprf command retrieves subscription copies of one or more profiles from the profile managers to which the current profile manager or endpoint (host or Network Information Services [NIS] domain) subscribes. This command updates the subscriber databases and configuration files from the Tivoli database. The name argument specifies an endpoint to which to send the copy. It can also specify the current profile copy.
If the –m argument is specified, a multistep distribution is performed from the profile manager. If –m is not specified, a single-step distribution is performed.
The –l argument identifies the distribution level. If unspecified, the default is maintain.
Authorization
admin, senior, super
Arguments
–l maintain | over_all Specifies the distribution level. The maintain argument keeps local modifications. The over_all argument overwrites local modifications.
–m Specifies a multistep distribution.
–r Sets the return code to 1 if at least one profile distribution or retrieval to or from a profile manager fails.
name Specifies the endpoint to which to send the copy, or a current profile copy. Valid formats for the name argument include the following:
wgetprf
1–264 Version 3.7
■ @node_name
■ @ManagedNode:node_name
■ /Regions/PolicyRegionName/node_name
EXAMPLES
1. The following example retrieves the profile copy Users from its source profile subscribee, rushmore, overwriting any local modifications:
wgetprf -l over_all @UserProfile:Users@rushmore
2. The following example retrieves all profile copies in managed node rushmore recursively, maintaining any local modification:
wgetprf -m @ManagedNode:rushmore
SEE ALSOwcrtpr, wcrtprfmgr, wgetsub, wlssub, wpopulate, wdistrib, wsub, wunsub
wgetquery
Tivoli Management Framework Reference Manual 1–265
Com
mands
wgetqueryLists information about a query.
SYNOPSISwgetquery [–f] query_name
DESCRIPTIONThe wgetquery command lists information about a Tivoli query. This information includes the name, description, repository, view, columns list, and where clause.
Authorization
query_view, user, admin, senior, or super
Arguments
–f Lists all information about the specified query. Without the –f argument, the wgetquery command returns only the where clause.
query_name Specifies the name of the query.
EXAMPLESThe following example lists all information about the DOS-machines query:wgetquery -f DOS-machines
The output is as follows:Name: DOS-machinesDescription: Query for DOS PCsRepository: inventoryView: MACHINE_TYPEColumns:
PROCESSOR_TYPEOPERATING_SYSTEM
Where Clause:--------------------(BOOTED_OS_NAME = ’DOS’)
wgetquery
1–266 Version 3.7
SEE ALSOwcrtqlib, wcrtquery, wgetquery, wsetquery, wruninvquery
wgetrim
Tivoli Management Framework Reference Manual 1–267
Com
mands
wgetrimLists information about an RDBMS Interface Module (RIM) object.
SYNOPSISwgetrim rim_name
DESCRIPTIONThe wgetrim command lists the current information for the specified RIM object.
Authorization
senior or super in Tivoli Management Region (TMR)
Arguments
rim_name Specifies the label of the RIM object. This can be either the Tivoli name registry label (such as @RIM:name) or the RIM label.
EXAMPLESThe following example returns the information for the inventory RIM object. For databases other than DB2, no value is available for the Instance Home field.wgetrim inventory
The output is as follows:RIM Host: amon-sulRDBMS User: tivoliRDBMS Vendor: DB2Database ID: amarDatabase Home: opt/ibmDB2/V.2.1Server ID: tcpipInstance Home: /data/DB2
SEE ALSOwcrtrim, wsetrim, wsetrimpw
wgetsched
1–268 Version 3.7
wgetsched Retrieves information about jobs currently scheduled.
SYNOPSISwgetsched [–b ‘mm/dd/yyyy hh:mm’] [–a ‘mm/dd/yyyy hh:mm’] [–v]
wgetsched [–s id [–s id] …] [–v]
DESCRIPTIONThe wgetsched command retrieves information about jobs currently scheduled to execute. If no options are specified, information about all jobs is displayed.
Authorization
user
Arguments
–b ‘mm/dd/yyyy hh:mm’ Specifies jobs that are scheduled to execute before this time.
–a ‘mm/dd/yyyy hh:mm’ Specifies jobs that are scheduled to execute after this time.
–s id… Specifies the job ID. You can specify more than one job ID.
–v Specifies verbose mode.
EXAMPLESThe following are two examples of this command’s output, normal and verbose. The verbose output provides all information about all scheduled jobs. This output can be very large, so it is intended to be redirected to a file.
wgetsched
Tivoli Management Framework Reference Manual 1–269
Com
mands
Normal OutputJob ID Label Admin Date & Time Enbld Repeat Retry Cncl------ ----- ----- ----------- -----------------------000008 JOB #14 root@cook Fri May 6 01:00:00 1994 YES YES NO YES000002 JOB #2 root@cook Sun Jan 1 01:12:00 1995 YES NO NO NO000010 JOB #9 root@cook Wed Mar 1 06:55:00 1995 YES NO YES NO
Verbose OutputID : 2Name : BackupLabel : BackupDescription :Administrator : root@vernonOriginal Time : Tue Mar 05 16:00:00 1996Next Time : Tue Mar 05 16:00:00 1996Enabled : YesRepeat Type : InfiniteRepeat Increment : 1Repeat Unit : DayRepeat Times : 0Retry Type : NoneRetry Increment : 0Retry Unit : MinuteRetry Times : 0Cancel Job : YesCancel Increment : 10Cancel Unit : MinuteEmail :Notice : Tivoli Scheduler,Desktop :Host Name :File Name :Daytime Rest. : NoDaytime From : 6Daytime To : 18Nighttime Rest. : NoNighttime From : 17Nighttime To : 8Weekday Rest. : NoWeekday From : 1Weekday To : 5Weekend Rest. : YesWeekend From : 6Weekend To : 0
The next two examples show how to use the wgetsched command in combination with the –a and –b arguments.
wgetsched
1–270 Version 3.7
The following example lists all jobs scheduled to run before May 6, 1998, at 1:00 a.m. and after May 8, 1998, at 1:00 p.m. wgetsched –b '05/06/1998 01:00' –a '05/08/1998 13:00'
The following example lists all jobs scheduled to run after August 10, 1998, at midnight and before August 12, 1998, at 6:00 p.m.
wgetsched –a '08/10/1998 00:00' –b '08/12/1998 18:00'
SEE ALSOwdelsched, wenblsched, wschedjob, wedsched
wgetsub
Tivoli Management Framework Reference Manual 1–271
Com
mands
wgetsub Lists a profile manager’s subscribers.
SYNOPSISwgetsub[–l] [–o] name
DESCRIPTIONThe wgetsub command lists the Tivoli resources that subscribe to the profile manager specified in name.
Authorization
user, admin, senior, super
Arguments
–l Specifies a long listing.
–o Lists the object identifier for each profile manager’s subscribers.
name Specifies the name of the profile manager whose subscribers are to be listed. Valid formats for the name argument include the following:
■ @prof_manager_name
■ @ProfileManager:prof_manager_name
■ /Regions/PolicyRegionName/prof_manager_name
EXAMPLESThe following example lists all the subscribers of the Development profile manager. wgetsub @Development
SEE ALSOwcrtprf, wcrtprfmgr, wlssub, wpopulate, wgetprf, wdistrib, wsub, wunsub, wvalidate
wgettask
1–272 Version 3.7
wgettask Lists the properties of a task.
SYNOPSISwgettask [–F filename] task_name library_name
DESCRIPTIONThe wgettask command lists the properties of a task. The output of this command is sent to standard output.
Authorization
user, senior, super
Arguments
–F filename Specifies a file in which the task information is written. This argument creates a .tar file of the task binaries and comments as well as a description of the task settings. This argument is useful when exporting a task from one Tivoli environment to another.
task_name Specifies the name of the task to be listed.
library_name Specifies the name of the task library containing the specified task.
EXAMPLESThe following example lists all information about the Clean Queue task in the queue_lib task library. wgettask "Clean Queue" queue_libTask Name : Clean QueueUser ID : *Group ID :Task ACL : admin:senior:super:userSupported Platforms :solaris2
wgettask
Tivoli Management Framework Reference Manual 1–273
Com
mands
<install>/solaris2/TAS/TASK_LIBRARY/bin/200000/tasknpzmqdTask Documentation :
Task Name : Clean QueueTask Created : Wed Sep 14 20:20:16 1998Task Created By : root@yogiComments:-------------------------------------------
SEE ALSOwcrttask, wdeltask
wgetval
1–274 Version 3.7
wgetval Retrieves a registry subkey. This command should be run from an endpoint. (Windows 95, Windows 98, and Windows NT only)
SYNOPSISwgetval [–h registry_hive] –k {key | @filename} –n value_name
DESCRIPTIONThe wgetval command retrieves a subkey from a registry. The output of this command is returned to standard output.
Authorization
administrator
Arguments
–h registry_hive Specifies the registry hive from which to retrieve the subkey. Valid values are as follows:
■ HKEY_LOCAL_MACHINE
■ HKEY_CURRENT_USER
■ HKEY_CLASSES_ROOT
■ HKEY_USERS
■ HKEY_CURRENT_CONFIG
■ HKEY_DYN_DATA
–k key | @filename Specifies the key or file from which the subkey is retrieved.
–n value_name Specifies the name of the value.
wgetval
Tivoli Management Framework Reference Manual 1–275
Com
mands
EXAMPLESTo retrieve the version number of the Novell drivers, enter the following command:wgetval -h HKEY_LOCAL_MACHINE -k SOFTWARE\NOVELL \-n CurrentVersion
SEE ALSOwsetval
whostid
1–276 Version 3.7
whostid Prints the host ID of the specified managed node.
SYNOPSISwhostid host_name
DESCRIPTIONThe whostid command prints the host ID of the managed node specified in the host_name option.
Authorization
user, admin, senior, super
Argument
host_name The name of the host whose ID to list.
EXAMPLESThe following example shows the host ID of managed node bald: whostid bald8031ee30
SEE ALSOwdate, wdiskspace, wifconfig, winstdir, winterp, wmannode, wmemsize, wping, wtimezone, wuname, wxterm
wiconv
Tivoli Management Framework Reference Manual 1–277
Com
mands
wiconvConverts the characters or sequences of characters in a file from one code set to another code set.
SYNOPSISwiconv [–f codeset] [–t codeset <input | codeset > output] wiconv [–f codeset] [–t codeset] [–i input] [–o output]
DESCRIPTIONThe wiconv command converts the characters or sequences of characters in a file from one code set to another code set and then writes the results to standard output. Before using this command it is necessary to set the TISDIR environment variable.
Authorization
This command does not require any Tivoli Management Region (TMR) authorization roles to be executed.
Arguments
–f codeset Identifies the input code set.
–t codeset Identifies the output code set.
> output Writes the results to standard output.
< input Reads input data from standard input.
–i input Identifies the name of the input file instead of using the standard input.
–o output Identifies the name of the output file instead of using the standard output.
EXAMPLESThe following example takes the data in the file source.txt, converts it from SJIS encoding to UTF8 encoding, and then outputs the result to the file utf8.html:wiconv –f SJIS –t UTF8 –i source.txt –o utf8.html
wident
1–278 Version 3.7
wident Identifies files.
SYNOPSISwident [–q] [file …]
DESCRIPTIONwident searches for all occurrences of the pattern $keyword:…$ in the named file or, if no file name appears, the standard input.
These patterns are normally inserted automatically by the Revision Control System (RCS) command wco but can also be inserted manually. The argument –q suppresses the warning given if no patterns are in a file.
wident works on text files as well as object files and dumps. For example, if the C program in f.c contains the following:char rcsid[] = "$Id: f.c,v \*(iD $";
and f.c is compiled into f.o, the command wident f.c f.o
will output f.c:
$Id: f.c,v \*(iD $f.o:
$Id: f.c,v \*(iD $
SEE ALSOwci, wco, wrcs,wrcsdiff, wrcsmerge, wrlogWalter F. Tichy, RCS—A System for Version Control, Software—Practice & Experience15, 7 (July 1985), 637-654.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.0; Release Date: 1980/08/22. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990 by Paul Eggert.
widmap
Tivoli Management Framework Reference Manual 1–279
Com
mands
widmapLists and modifies user login mappings.
SYNOPSISwidmap list_maps
widmap add_map map_name
widmap rm_map map_name
widmap list_entries map_name
widmap add_entry map_name interp entry_val
widmap rm_entry map_name interp
widmap resolve_entry map_name interp
DESCRIPTIONThe widmap command enables you to create and maintain mappings of user logins across multiple platforms. A login map enables Tivoli to associate a single user login name with the correct user account on a specified operating system. For example, the login name chris might be mapped to user name chriss on Solaris systems and to user name chris_sanders on Windows NT systems.
The following example shows two login mappings; one for root_user and one for chris:root_user default rootroot_user w32-ix86 Administratorchris solaris2 chrisschris w32-ix86 chris_sanders
Map names can be entered into Tivoli dialogs as $map_name. For example, $chris can be entered into the Login Name or Group Name fields of the Create Administrator dialog. $chris then resolves to the correct user name depending on the system being used.
The widmap command creates, list, adds, and deletes entire maps or entries of a map.
Authorization
widmap requires the user role to view maps and the super role to create, edit, or delete maps.
widmap
1–280 Version 3.7
Arguments
list_maps Lists the existing maps.
add_map Adds a map for map_name.
rm_map Removes map_name.
list_entries Lists the existing entries for map_name.
add_entry Adds an entry to map_name.
rm_entry Removes interp from map_name.
resolve_entry Returns entry_val of the specified interp.
map_name Identifies the mapping to be viewed or modified.
interp Identifies the interpreter type or operating system on which entry_val is a valid user name. Specifying interp as default indicates the default entry_val should be used on any operating system that does not have a separate interp entry.
entry_val Identifies the user name to which map_name will resolve.
EXAMPLES
1. The following example lists all mappings:
widmap list_maps
2. The following example adds a default entry to the $chris map:
widmap add_entry chris default chris
As a result of this command, the $chris map looks like this:
chris solaris2 chrisschris w32-ix86 chris_sanderschris default chris
3. The following example removes the solaris2 entry from the $chris map:
widmap rm_entry chris solaris2
4. The following example returns the user name mapped in the $chris map to the default interpreter type:
widmap resolve_entry chris default
widmap
Tivoli Management Framework Reference Manual 1–281
Com
mands
The result of this command is chris.
Note: If the same command were run for the HP-UX operating system, the result would be the same. Because there is not an entry for HP-UX, the default value is returned.
wifconfig
1–282 Version 3.7
wifconfig Queries or changes the Internet Protocol (IP) interfaces on a managed node.
SYNOPSISwifconfig –h node_name wifconfig –h node_name –a device address name notify_server wifconfig –h node_name –r device [address name] wifconfig –h node_name –s device address name notify_server
DESCRIPTIONThe wifconfig command allows you to query or change the IP interfaces on a managed node in the Tivoli environment.
Authorization
To query: user, admin, senior, super
To change: admin, senior, super
Arguments
–h node_name Specifies the managed node on which you are querying or changing the IP interfaces.
–a (UNIX only) Adds an IP interface to the managed node. You must specify a device, IP address, and name for the interface. You must also indicate whether the Tivoli Management Region (TMR) server should be notified about the new IP interface.
–r (UNIX only) Removes an IP interface from the managed node. You must specify the device name. You can also optionally specify the IP address and interface name.
–s (UNIX only) Changes the settings of a current IP interface. You must specify the device name and the new interface definition (IP address, interface name, and whether the TMR server knows about the interface). You cannot change the device name with the –s argument.
wifconfig
Tivoli Management Framework Reference Manual 1–283
Com
mands
device Specifies the device used by the interface.
address Specifies the IP address of the interface.
name Specifies the name of the interface.
notify-server Controls whether the TMR server in the local TMR is notified of the addition or modification of the IP interface. This argument’s value must be TRUE or FALSE.
EXAMPLES
1. The following example queries the IP address of the managed node bald:
wifconfig -h baldDevice Address Name Used by dispatcherlo0 127.0.0.1 localhost unused
2. The following example adds an IP interface for managed node bald. The device is lel, the IP address is 146.84.49.3, and the interface name is bald2. The TMR server will be notified of the new interface.
wifconfig -h bald -a lel 146.84.49.3 bald2 TRUE
3. The following example removes IP interface bald2 from managed node bald.
wifconfig -h bald -r lel 146.84.49.3 bald2
SEE ALSOodadmin, netstat(1)
winsblk
1–284 Version 3.7
winsblkInserts a block of statements into a file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwinsblk –s “search_string” {–a “insertion_string” | @filename} | {–b “insertion_string” | @filename} [–o output_file] filename
DESCRIPTIONThe winsblk command inserts a block of statements into a file. This command enables you to add a block of statements delimited by unique strings, which you can later search for or remove using the wrplblk or wclrblk commands.
Arguments
–a “insertion_string” | @filename Inserts a block of statements after the line containing the search string. This parameter cannot be specified with the –b argument.
If you specify insertion_string, you must surround the string with double quotation marks. If you specify @filename, this command inserts the block of statements from the specified file.
–b “insertion_string” | @filename Inserts a block of statements before the line containing the search string. This parameter cannot be specified with the –a argument.
If you specify insertion_string, you must surround the string with double quotation marks. If you specify @filename, this command inserts the block of statements from the specified file.
–o output_file Writes that output to the file specified by output_file. If this parameter is not specified, output is written to standard output.
winsblk
Tivoli Management Framework Reference Manual 1–285
Com
mands
–s “search_string” Specifies a search string. If the search string is contained in a line, the block of statements is placed either before (using the –b argument) or after (using the –a argument) the line containing the search string. If this argument is not specified, the block of statements is appended to the file.
filename Specifies the file to insert the block into.
RETURNSwinsblk returns one of the following:
0 Indicates that winsblk successfully added the specified block of statements.
nonzero Indicates that winsblk did not successfully add the specified block of statements.
EXAMPLESTo insert the statements in the BLKSTMTS.FIL file after every occurrence of the device= string in the SYSTEM.INI file and redirect output to the OUTPUT.FIL file, enter the following command:winsblk -s "device=" -a @C:\TEMP\BLKSTMTS.FIL \-o C:\TEMP\OUTPUT.FIL C:\WINDOWS\SYSTEM.INI
SEE ALSOwrplblk, wclrblk, winsline
winsline
1–286 Version 3.7
winsline Inserts a single line into a file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwinsline [–f] –s “search_string” {–a “insertion_string” | –b “insertion_string”} [–o output_file] filename
DESCRIPTIONThe winsline command adds a line to a text file. You can insert the line before or after a line that contains the search string.
Arguments
–a “insertion_string” Inserts the specified string or the lines contained in the specified file after the line that contains the search string. This parameter cannot be specified with the –b argument. You must surround the string with double quotation marks.
–b “insertion_string” Inserts the specified string or the lines contained in the specified file before the line that contains the search string. This parameter cannot be specified with the –a argument. You must surround the string with double quotation marks.
–f Processes only the first occurrence of the search string. If this argument is not specified, the command processes each occurrence of the search string.
–o output_file Specifies that output will be written to a file named output_file. If this parameter is not specified, output is written to standard output.
winsline
Tivoli Management Framework Reference Manual 1–287
Com
mands
–s “search_string” Specifies the search string. If the search string is contained in a line, the insertion string is placed either before (using the –b argument) or after (using the –a argument) the line containing the search string. You must surround the string with double quotation marks.
filename Specifies the name of the file to insert the line into.
RETURNSwinsline returns one of the following:
0 Indicates that winsline successfully added the specified line.
nonzero Indicates that winsline did not successfully add the specified line.
EXAMPLES
1. To insert lp01 after the first occurrence of the device= string in the SYSTEM.INI file and redirect output to the OUTPUT.FIL file, enter the following command:
winsline -f -s "device=" -a "lp01" -o C:\TEMP\OUTPUT.FIL \
C:\WINDOWS\SYSTEM.INI
2. To insert dev01 before every occurrence of the type= string in the SYSTEM.INI file, enter the following command:
winsline -s "type=" -b "dev01" -o C:\TEMP\OUTPUT.FIL \
C:\WINDOWS\SYSTEM.INI
The output from this command is redirected from standard output to the file OUTPUT.FIL.
SEE ALSOwrplline, wclrline, winsblk
winstall
1–288 Version 3.7
winstall Installs a Tivoli product.
SYNOPSISwinstall [–c source_dir] [–s server] [–i product] [–y] [install_variables] [–n | managed_node…]
DESCRIPTIONThe winstall command installs a Tivoli product from the command line when invoked on the Tivoli Management Region (TMR) server. Before installing any product, this command identifies the actions that will be performed during the installation.
Authorization
Requires install_product or senior in the TMR
Arguments
–c source_dir Specifies the complete path to the directory containing the installation image.
–i product Specifies the product index file from which the product is installed. Index files have an IND extension. For example, the index file for Tivoli User Administration is ADMIN.IND. You can specify this product as –i ADMIN or –i ADMIN.IND.
–n Installs the product on all managed nodes that do not currently have the product installed. This argument is ignored when managed_node is specified.
–s server Specifies the managed node to use as the installation server. If not specified, the server is the TMR server.
–y Installs the product without requesting confirmation.
install_variables Specifies product-specific keyword=value pairs. For details, see the following section, “Installation Variables.”
winstall
Tivoli Management Framework Reference Manual 1–289
Com
mands
managed_node Specifies the managed nodes on which to install this Tivoli product. You can specify multiple managed nodes. If you do not specify a managed node, the product is installed on all managed nodes in this TMR.
INSTALLATION VARIABLESYou specify values for installation variables on the command line to control the installation. If a Tivoli product has installation variables, you can view the index (.IND) file for that product for its definitive list of installation variables. Use these variables to specify required and optional arguments as well as to override default installation information.
You can use installation variables to specify the directories where a Tivoli product is to be installed. Specify these directories when you install Tivoli Management Framework; other Tivoli products will use the same directories as Tivoli Management Framework. If a directory already contains the files, the files are not reinstalled. You can, however, force any of these directories to be overwritten by entering an exclamation mark (!) as the value for the specified directory. For example, to reinstall the binaries, you would enter BIN=! instead of entering the entire path to the binaries directory. This override feature applies to all installation variables.
The following are the variables related to installation directories:
BIN=binaries_dir Overrides the default installation path for the product binaries (/usr/local/Tivoli/bin).
LIB=libraries_dir Overrides the default installation path for the product libraries (/usr/local/Tivoli/lib).
DB=client_database Overrides the default installation path for the product client database (/var/spool/Tivoli).
MAN=manpage Overrides the default installation path for the product man pages (/usr/local/Tivoli/man).
winstall
1–290 Version 3.7
CAT=message_catalog Overrides the default installation path for the product message catalogs (/usr/local/Tivoli/msg_cat).
The following is another useful variable:
@CreatePaths@=[0 | 1] Indicates whether to create (1) or not to create (0) any specified directory if it does not already exist. By default, directories are not created. You will receive an error message if a specified directory does not exist.
EXAMPLES
1. The following example installs Tivoli User Administration on all managed nodes in the TMR. The path to the installation image is /cdrom, and the product index file is ADMIN.
winstall -c /cdrom -i ADMIN
2. The following example installs Tivoli Software Distribution on managed nodes dan and barney. The path to the installation image is /dev0/cdrom, and the product index file is COURIER.
winstall -c /dev0/cdrom -i COURIER dan barney
3. The following example reinstalls Tivoli User Administration on managed node dan, overwriting existing files in the binary directory. The path to the installation image is /cdrom and the product index file is ADMIN.TMR with the use of the BIN argument:
winstall -c /cdrom -i ADMIN BIN=!
SEE ALSOwserver, wclient, wpatch
winstdir
Tivoli Management Framework Reference Manual 1–291
Com
mands
winstdir Prints the path of the installation directory of the specified managed node.
SYNOPSISwinstdir host_name
DESCRIPTIONThe winstdir command prints the path of the installation directory of the managed node specified in the host_name option.
Authorization
user, admin, super, senior
Argument
host_name The name of the host whose installation directory to list.
EXAMPLESThe following example shows the installation directory for the managed node bald: winstdir bald/data/shadow/solaris2/as/bin
SEE ALSOwdate, wdiskspace, whostid, wifconfig, winterp, wmannode, wmemsize, wping, wtimezone, wuname, wxterm
winstendpt
1–292 Version 3.7
winstendpt Installs behavior for an endpoint resource type.
SYNOPSISwinstendpt endpoint_behavior [endpoint_res_type]
DESCRIPTIONThe winstendpt command installs behavior onto an endpoint resource type. If a profile-based application defines an endpoint behavior, that behavior can be added to the inheritance of an endpoint resource type such as a managed node.
This command would normally be run from the initialization script of a profile-based application.
Authorization
super, senior
Arguments
endpoint_behavior Identifies the instance manager of the new endpoint behavior resource type.
endpoint_res_type Identifies the endpoint resource type on which the new behavior will be installed. If no endpoint_res_type is given, the managed node resource type is assumed.
EXAMPLESThe following example installs the endpoint behavior of resource type aef onto the ManagedNode resource type: aef_CO=‘wlookup -r Classes aef‘managednode_CO=‘wlookup -r Classes ManagedNode‘winstendpt $aef_CO $managednode_CO
winstlcf
Tivoli Management Framework Reference Manual 1–293
Com
mands
winstlcfInstalls an endpoint on UNIX, Windows NT, and Windows 2000 workstations.
SYNOPSISwinstlcf [–a] [–d dir_name] [–e] [–f file_name] [–g machine[+port] [:machine[+port]] [–i] [–l ep_port] [–L config_args] [–N endpoint] [–n endpoint_label] [–P] [–R] [–r Policy_region] [–S share_name] [–s dir_name] [–T account] [–v] [–Y] host [user_acct passwd] …
DESCRIPTIONThe winstlcf command installs and starts the endpoint daemon (lcfd) on one or more workstations. This command installs UNIX, Windows NT, and Windows 2000 endpoints only. By default, endpoints start automatically after installation. You can install multiple endpoints by listing the machine names on the command line or by specifying a file containing the machine names. The file must contain one machine name on each line of the file.
If you run winstlcf on a machine more than once, you will have more than one instance of lcfd running on that machine. Only one instance of lcfd should exist on each machine. Remove any additional instances.
Note: Because Windows NT does not have a remote execution service, the first Windows NT endpoint in a domain must be manually installed with InstallShield. You can then use winstlcf with the –N argument to reference that endpoint as a proxy to install all other Windows NT endpoints within the same domain or trust.
After you specify an installation password with the winstlcf command, that password becomes the default for all subsequent installations. The following three actions change the password:
1. You explicitly specify another password.
2. You attempt an installation on an unsupported operating system, which erases the global variable containing the password.
3. You specify the –P argument.
winstlcf
1–294 Version 3.7
Authorization
No Tivoli authorization role is required.
Argument
–a Specifies that endpoints be installed asynchronously. Without this argument, winstlcf waits for the endpoint to log in to its gateway before installing the next endpoint.
–d dir_name Specifies the target directory in which to install the endpoint software. The default location is /opt/Tivoli/lcf for UNIX and c:\Tivoli\lcf for Windows NT and Windows 2000. When installing a Windows NT or Windows 2000 endpoint from a UNIX server, forward slashes in path names are also supported.
–e This is a UNIX argument. Uses the shell service instead of exec.
–f file_name Specifies a file name containing a list of machine names on which to install the endpoint software. The file must contain one machine name per line with the user ID and password that will be used to install the endpoint. For example, the following could be two lines in the file:
red root mstr_Keyorange chris d1n0mite
–g machine[+port][:machine[+port]]… Specifies the Internet Protocol (IP) address or host name and, optionally, the port number of the gateway to which the endpoint will log in. Multiple gateway entries must be separated by colons (:). You must specify the port number if it is other than 9494, the default. If the –g argument is omitted, the endpoint will broadcast to all gateways.
–i Turns off auto-start configuration for a UNIX endpoint after installation. By default, Windows NT endpoints always start automatically after installation.
winstlcf
Tivoli Management Framework Reference Manual 1–295
Com
mands
–l ep_port Specifies the port number for the endpoint. The default port number is 9495.
–L config_args Passes configuration arguments to the lcfd command for starting the endpoint. See the lcfd command for a list of valid arguments. If you pass multiple arguments or have spaces in a single argument, you must enclose the text in quotation marks.
–N endpoint Specifies an existing Windows NT endpoint from which you can remotely install other Windows NT endpoints. When you use this option, winstlcf assumes that all endpoints to be installed are Windows NT clients. Installing the Tivoli Remote Execution Service (TRIP) is not necessary.
–n endpoint_label Specifies an endpoint label provided by a user.
–P Causes winstlcf to prompt for a password for each machine. This argument is useful only when installing on remote hosts with different passwords. If each machine has the same password or if you do not use the –P argument, winstlcf prompts for a global password to use for each machine.
–R Requires the Windows NT endpoint to reboot after installation without prompting the user. This argument is only needed if the Tivoli Authentication Package (TAP), TivoliAP.dll, was not previously installed on the endpoint or an older version of TAP is being replaced.
–r policy_region Specifies a policy region where to install the endpoint.
–S share_name Specifies a destination share name (default = C$).
–s dir_name Specifies the source directory containing the endpoint installation image.
–T account Specifies the Tivoli Remote Access Account (TRAA) for the Windows NT endpoint.
winstlcf
1–296 Version 3.7
–v Lists verbose installation information and error messages.
–x NetWare only. Specifies the protocol used by the endpoints to be installed. Supported protocols are Transmission Control Protocol/Internet Protocol (TCP/IP) and Internetwork Packet Exchange (IPX). To specify both TCP/IP and IPX, specify the argument as –x TCPIP,IPX. The default is TCP/IP, and you cannot remove it.
–Y Specifies that the installation should proceed without confirmation. By default, this command identifies the actions that must be taken to perform the installation and requests confirmation before continuing. Using this argument, winstlcf identifies the actions and performs the installation without requesting the confirmation.
host [user_acct passwd] Specifies the name of the machine on which the endpoint will be installed. If you specify only the host name, the root or Administrator account will be used. You will be prompted for the password. You can specify a different user account and password by enclosing the three entries in quotation marks. For example, you might enter the following:
winstlcf ’vernon DOMAIN-NT\chris d1n0mite’
If the Windows NT domain and the local computer use the same user_acct name (such as Administrator), you must specify the fully qualified name for the account, as in the preceding example. Quotation marks are necessary when specifying fully qualified user accounts.
winstlcf
Tivoli Management Framework Reference Manual 1–297
Com
mands
EXAMPLES
1. The following example installs the endpoint software on a UNIX workstation named vernon and starts the endpoint daemon (lcfd). winstlcf uses the root account and prompts for the root password on vernon. The installation image will be placed in the default directory. The endpoint will start with the default configuration.
winstlcf vernon
2. The following example installs the endpoint software on a Windows NT workstation named olympus and starts the endpoint service. winstlcf uses the Administrator account and prompts for the Administrator password on olympus. The installation image is taken from a Windows NT proxy named fuji (a previously installed Windows NT endpoint). The software is installed in the default directory on the olympus computer. The endpoint starts with the default configuration.
winstlcf -N fuji olympus
3. The following example installs the endpoint on a Windows NT workstation in a directory other than the default directory. In this example, the endpoint is installed on workstation bonnell on drive D with the share name steve. For instances where the share name of the destination drive is not the default name (D:\ = D$), –d specifies the directory D:\tivoli\lcf, and –S specifies the share name steve.
winstlcf -N pctmp107 -d D:\tivoli\lcf -S steve bonnell
4. The following example installs the endpoint software on workstation bbunny. The endpoint performs its initial login through IP address 123.45.1.12.
winstlcf -g 123.45.1.12 bbunny
5. The following example installs the endpoint on workstation bbunny and passes configuration arguments to the lcfd command to use when it starts the endpoint. In the example, –g cedar+1616 specifies the gateway and port that the endpoint contacts for initial login. –D lcs.machine_name=endpoint_name assigns a specific name to the endpoint.
winstlcf -L ’-g cedar+1616 \-D lcs.machine_name=bbunny-ep’ bbunny
winstlcf
1–298 Version 3.7
6. The following example installs machines cedar and mahogany as endpoints. The installation process prompts for a global root password, but does not prompt for confirmation before installing.
winstlcf -P -Y cedar mahogany
7. The following example installs multiple endpoints from the endpt.txt file. The installation process does not prompt for password or installation confirmation. The software is installed in /usr/lcf.
winstlcf -f endpt.txt -Y -d /usr/lcf
8. The following example installs a Windows NT endpoint on the machine agodino using IPX to connect to the NetWare gateway lux, and using IPX to give the machine name as antonella by using the endpoint vernon as a proxy.
winstlcf –xIPX –N vernon –g LUX+7787 –nantonella agodino
SEE ALSOlcfd.sh, wdelep
winstruct
Tivoli Management Framework Reference Manual 1–299
Com
mands
winstructProvides Tivoli Management Framework with information necessary to install and manage an application.
SYNOPSISwinstruct –a amp_file –s staging_area [–t admin_tag][–D variable=value] …
DESCRIPTIONThe winstruct command passes information about an application to Tivoli Management Framework and certain Tivoli tools installed in the environment. Tivoli uses the information to distribute, install, and manage the application. In this context, Tivoli Management Framework is an application management tool.
The winstruct command first reads an application management package (AMP) and extracts its contents into a staging area directory. The contents of the AMP are an .aof, a .gdf, and one or more .cdf files. These are application description files based on the Application Management Specification (AMS). The AMP can also contain the source files that make up the application.
The command then calls the appropriate winstruct subcommand for each installed Tivoli tool. The winstruct command passes any arguments it receives to the subcommands. The winstruct command and subcommands use the contents of the AMP to inform, or instruct, Tivoli Management Framework and the tools about information they need to install and manage the application.
The winstruct, winstruct_task, and winstruct_plus commands are included in the Tivoli Management Framework installation. The remaining commands are installed when the Tivoli products are added to the environment. The following list summarizes the commands and products with which they are installed:
winstruct Installed with Tivoli Management Framework
winstruct_event Installed with Tivoli Enterprise Console
winstruct_file Installed with Tivoli Software Distribution
winstruct
1–300 Version 3.7
winstruct_inventory Installed with Tivoli Inventory
winstruct_monitor Installed with Tivoli Distributed Monitoring
winstruct_plus Installed with Tivoli Management Framework
winstruct_task Installed with Tivoli Management Framework
The winstruct subcommands ignore a repeated instruction, which permits the instruction process to continue for the remaining uninstructed tools. For example, suppose you execute the winstruct command for an application, but the process does not complete for some reason. When you correct the problem and issue the command again, the instruction process continues from the point where it halted.
Authorization
policy in addition to senior or super
Arguments
–a amp_file Specifies the path and file name of an AMP.
–s staging_area Specifies a directory into which the winstruct command extracts the contents of the AMP.
–t admin_tag Specifies an administrator tag for the instruct action. Unique administrator tags enable the instructing of multiple versions of an AMP.
–D variable=value Specifies the name of an arbitrary variable and its value. You can specify multiple variables, but you must enter –D for each variable and value pair. Tivoli Management Framework and Tivoli products all receive the same environment variables passed with –D, but each management tool uses only those variables that apply to the tool. The tools ignore irrelevant variables.
winstruct
Tivoli Management Framework Reference Manual 1–301
Com
mands
EXAMPLESTo instruct the Tivoli system with information for managing an application, enter the following:winstruct -a /applications/amps/super_amp.amp \-s /install/staging -t rev1 -D src_dir=/cdrom
This command extracts the contents of the .amp file into the /install/staging directory. The command then reads the contents, which are an .aof, a .gdf, and one or more .cdf description files. The command checks the system for the presence of Tivoli tools. The winstruct command executes the appropriate subcommand for each tool it detects, passing to the subcommands any arguments issued for the main command. For example, if it finds Tivoli Software Distribution and Tivoli Distributed Monitoring, winstruct calls the winstruct_file and winstruct_monitor subcommands.
The instruction process is labeled with the “rev1” tag. The tag distinguishes this version of the AMP from others. In this example, the application files are not included in the AMP, but are instead located on a CD, specified with the –D argument. The command checks the Management Tool Extension Group (specified in the Application Management Specification [AMS]) for variable=value pairs and command line arguments to determine the source directory for the application files.
SEE ALSOwinstruct_event, winstruct_ file, winstruct_inventory, winstruct_monitor, winstruct_plus, winstruct_task
winstruct_plus
1–302 Version 3.7
winstruct_plusCreates Tivoli Application Management modules from Application Management Specification (AMS) files produced by the Tivoli Module Builder.
SYNOPSISwinstruct_plus –a amp_file –s staging_area [–t admin_tag] [–D variable=value] …
DESCRIPTIONThe winstruct_plus command, a subcommand of winstruct, extracts the contents of the application management package file (.amp) into a specified staging area. The subcommand reads the extracted application description files (.aof, .gdf, and one or more .cdf), which are based on the AMS. If these files include Management Tool Extension Group (MTEG) variables that have been generated by the Tivoli Module Builder, winstruct_plus recognizes the variables and uses the information to create a Tivoli Application Management module for the application. A Tivoli Application Management module created in this way provides a common interface for managing the application. Features in the Tivoli Application Management module interface include application launch, indicator collections, and subscription lists. The interface also includes a view of, and access to, pertinent Tivoli information and objects that have already been created by the winstruct_file, winstruct_monitor, and winstruct_task subcommands. Objects include the following:
■ Sentry profiles
■ File packages
■ Tasks
Because winstruct_plus refers to information and objects that are created by other subcommands, the winstruct command calls winstruct_plus last. If a .gdf or .cdf file contains Tivoli Application Management Tool Extension variables that relate to a Tivoli object not yet created by another winstruct subcommand, winstruct_plus ignores the variables until they are invoked again. If an administrator later issues the winstruct command and the subcommands create the required data
winstruct_plus
Tivoli Management Framework Reference Manual 1–303
Com
mands
objects, winstruct_plus provides information for managing the component with the Tivoli Application Management module.
The winstruct_plus subcommand uses information that is provided in Tivoli Application Management MTEG variables. These variables and component information recognized by the winstruct subcommands are included in the .gdf and .cdf files generated by the Tivoli Module Builder. If a .gdf or .cdf file does not contain Tivoli Application Management MTEG variables, other winstruct subcommands might process the information, but winstruct_plus skips it. The corresponding component will not be managed with a Tivoli Application Management module.
The winstruct_plus subcommand ignores a repeated instruction, which permits the instruction process to continue for the remaining uninstructed tools. For example, suppose you execute the winstruct command for an application, but the process does not complete for some reason. When you correct the problem and issue the command again, the instruction process continues from the point where it halted.
You can execute this command directly instead of calling it from the winstruct command. However, if winstruct_plus variables relate to objects not yet created, the Tivoli Application Management module does not manage the corresponding component. Typically, this subcommand requires the winstruct_task subcommand to have been issued first.
Authorization
policy in addition to senior or super
Arguments
–a amp_file Specifies the path and file name of an AMP.
–s staging_area Specifies a directory into which the winstruct_plus command extracts the contents of the AMP.
–t admin_tag Specifies an administrator tag for the instruct action. Unique administrator tags enable the instructing of multiple versions of an AMP.
winstruct_plus
1–304 Version 3.7
–D variable=value Specifies the name of an environment variable and its value. You can specify multiple variables, but you must enter –D for each variable and value pair.
EXAMPLESTo instruct a Tivoli Application Management Module with information for managing an application, enter the following:winstruct_plus -a /applications/amps/super_app.amp \-s /install/staging -t rev1
This command extracts the contents of the super_app AMP into the /install/staging directory and reads the .aof, .gdf, and .cdf description files. The instruction process is labeled with the “rev1” tag. The tag distinguishes this version of the AMP from others.
SEE ALSOwinstruct, winstruct_task
winstruct_task
Tivoli Management Framework Reference Manual 1–305
Com
mands
winstruct_taskProvides Tivoli Management Framework with the information to create tasks and dependencies for installing and managing an application.
SYNOPSISwinstruct_task –a amp_file –s staging_area [–t admin_tag][–D variable=value] …
DESCRIPTIONThe winstruct_task command, a subcommand of winstruct, extracts the contents of the application management package file (.amp) into a specified staging area. The subcommand reads the extracted application description files (.aof, .gdf, and one or more .cdf), which are based on the Application Management Specification (AMS). If it does not already exist, winstruct_task creates a top-level Applications policy region. The subcommand then creates subordinate policy regions, one for each revision level of the application.
The winstruct_task subcommand examines each .cdf file for the presence of particular groups of information and creates data objects for those it finds. The following list summarizes the groups and objects they create:
Operational Task group Task library
Generic Dependency Type group Dependency library
Generic Dependency Instance group Dependency instance
The winstruct_task subcommand ignores a repeated instruction, which permits the instruction process to continue for the remaining uninstructed tools. For example, suppose you execute the winstruct command for an application, but the process does not complete for some reason. When you correct the problem and issue the command again, the instruction process continues from the point where it halted.
You can execute this command directly—instead of calling it from the winstruct command—because winstruct_task is not dependent on any of the other winstruct subcommands.
winstruct_task
1–306 Version 3.7
Authorization
policy in addition to senior or super
Arguments
–a amp_file Specifies the path and file name of an AMP.
–s staging_area Specifies a directory into which the winstruct_task command extracts the contents of the AMP.
–t admin_tag Specifies an administrator tag for the instruct action. Unique administrator tags enable the instructing of multiple versions of an AMP.
–D variable=value Specifies the name of an environment variable and its value. You can specify multiple variables, but you must enter –D for each variable and value pair.
EXAMPLESTo instruct the Tivoli system with information for managing an application, enter the following:winstruct_task -a /applications/amps/super_app.amp \-s /install/staging -t rev1
This command extracts the contents of the super_app AMP into the /install/staging directory and reads the .aof, .gdf, and .cdf description files. The instruction process is labeled with the “rev1” tag. The tag distinguishes this version of the AMP from others.
SEE ALSOwinstruct
winterp
Tivoli Management Framework Reference Manual 1–307
Com
mands
winterp Prints the interpreter type of the specified managed node.
SYNOPSISwinterp host_name
DESCRIPTIONThe winterp command prints the interpreter type for the managed node specified in the host_name option.
Authorization
user, admin, senior, super
Argument
host_name Specifies the name of the host for which to list the interpreter type.
EXAMPLESThe following example shows the interpreter type of the managed node bald: winterp baldsolaris2
SEE ALSOwdate, wdiskspace, whostid, wifconfig, winterp, wmannode, wmemsize, wping, wtimezone, wuname, wxterm
wlcftap
1–308 Version 3.7
wlcftap Sets the properties of the Tivoli Authentication Package (TAP) on a Windows NT client. This command should be run from an endpoint.
SYNOPSISwlcftap [–a] [–d] [–r [domain_name\user_name|user_name]] [–k]
DESCRIPTIONThe wlcftap command sets the properties of the TAP, TivoliAP.dll. The TAP enables Tivoli to access remote file systems in the context of a user. (See the Tivoli Management Framework Planning for Deployment Guide for additional information on accessing remote file systems.) It also enables Windows NT to run setuid methods, that is, to run a method in the context of a user associated with the method.
The Tivoli Remote Access Account (TRAA) specifies a user account. Tivoli uses this account to access remote file systems.
Using the wlcftap command with no arguments prints version information from the currently running TivoliAP.dll.
When activating the TAP for the first time, which is usually immediately following Tivoli Management Region (TMR) server installation, you must reboot the machine for the TAP changes to take effect.
Authorization
Member of the Administrators group. Tivoli admin authorization is required to run wlcftap with no arguments.
Arguments
–a Sets the TAP internal key and registers the TivoliAP.dll with the local security authority (LSA). The new internal key becomes effective immediately. The TivoliAP.dll file is loaded by the LSA when the machine is rebooted.
wlcftap
Tivoli Management Framework Reference Manual 1–309
Com
mands
–d Removes the TAP internal key and unregisters the TivoliAP.dll with the local security authority (LSA). The TivoliAP.dll file is released by the LSA (so it can be deleted if Tivoli is uninstalled) when the machine is rebooted.
–r [domain_name\user_name|user_name] Sets the TRAA to user_name. Tivoli accesses remote file systems using this user account. user_name can be prefixed with the domain name, separated by either a forward slash (/) or a backslash (\). If the domain is specified, it must be the domain in which the machine running TAP belongs or a domain trusted by that domain. If no domain is specified, Windows NT looks for the given user in the local domain or trusted domains. wlcftap –r "" disables Tivoli access to remote file systems. To see changes take effect immediately, restart the object dispatcher.
–k Specifies that wlcftap should read the password for user_name from standard input. If you do not specify –k, wlcftap prompts you for the password.
EXAMPLESThe following example sets the TRAA to a user account called userTME. wlcftap reads the password for userTME from the file pswd.file.wlcftap -r userTME -k < pswd_file
wln
1–310 Version 3.7
wln Links an object into a collection.
SYNOPSISwln [–I] label… collection
DESCRIPTIONThe wln command links an object with the specified label into the selected collection. The label and collection arguments can both be full or partial label paths.
If you use this command to link an endpoint, run the wep sync_gateways command to synchronize the endpoint data stored by the endpoint manager, gateways, and endpoints within the Tivoli Management Region (TMR).
Authorization
admin, senior, super
Arguments
–I Ignores all failed suboperations, allowing the command to continue. This argument is useful only when multiple labels are passed to the command. The –I argument allows a link operation to fail for individual objects, but the command continues to the next object to be linked. Without this argument, if a link operation fails for an individual object, the command unlinks any objects already linked, and then the command terminates with error. The default is for the command to fail when the suboperation fails.
label… The object’s label. This argument can be a full label path (starting at the ‘/’ collection), a partial label path (relative to the current working collection), or a simple name (to be found in the current working collection).
wln
Tivoli Management Framework Reference Manual 1–311
Com
mands
collection The label of the collection into which the object is to be linked. This argument also can be a full label path (starting at the ‘/’ collection), a partial label path (relative to the current working collection), or a simple name (to be found in the current working collection). The linked object becomes a member of the selected collection.
EXAMPLESThe following example creates a new administrator using the command and then uses wln to link the server Region, and scheduler objects from the default root desktop into the newly created administrator’s desktop collection:wcrtadmin -a jack -r global,backup:admin:user \-r @ceridwen-region,admin:senior:user \-r @Administrators,admin:user -r @Scheduler,admin:user \-n "Tivoli Administration" -n "Tivoli Authorization" \-n "Tivoli Diagnostics" -n "Tivoli Scheduler" -u jack -g staff \"Jack Frost"wln /Administrators/Root_ceridwen-region/ceridwen-region \/Administrators/"Jack Frost"wln /Administrators/Root_ceridwen-region/Scheduler \/Administrators/"Jack Frost"
SEE ALSOwmv, wep
wlocalhost
1–312 Version 3.7
wlocalhost Sets the name of the local host in the Windows NT registry.
SYNOPSISwlocalhost [host_name]
DESCRIPTIONThe wlocalhost command sets the local host name in the Windows NT registry. If you do not specify host_name, wlocalhost returns the host name currently stored in the registry.
Authorization
Member of the Administrators group
Arguments
host_name Specifies the name of the local host.
wlocktmr
Tivoli Management Framework Reference Manual 1–313
Com
mands
wlocktmr Places the current Tivoli Management Region (TMR) in maintenance mode.
SYNOPSISwlocktmr –p wlocktmr –e cmdstring
DESCRIPTIONThe wlocktmr command places the current TMR in maintenance mode. In this mode you can perform various maintenance and diagnostic tasks. Note that issuing this command immediately terminates all active Tivoli processes.
You can invoke wlocktmr in two ways. The first way is to place the TMR in maintenance mode indefinitely. To do this, use the –p argument. The –p argument puts the TMR in maintenance mode and pauses until the process is terminated. You can perform maintenance and diagnostic operations in another window.
The second way to invoke wlocktmr is to run a single maintenance command or to run a batch or script file. To do this, use the –e argument. The –e argument puts the TMR in maintenance mode, runs the specified command or file, and exits maintenance mode.
Use the vi command (or any text editor) to create the list of commands. Use chmod to make sure that the commands are executable. Then run the wlocktmr command with the –e argument and the name of the command file.
Authorization
super
Arguments
–p Places the TMR in maintenance mode and pauses until you kill the process.
wlocktmr
1–314 Version 3.7
–e cmdstring Places the TMR in maintenance mode, runs the command given by cmdstring, and exits maintenance mode. cmdstring can be the name of a batch or script file.
wlocpath
Tivoli Management Framework Reference Manual 1–315
Com
mands
wlocpathReturns the path for the localized file or directory. This is the command line interface (CLI) command for the tis_get_loc_path function.
SYNOPSISwlocpath path [–d default_path] [–l language] [–o output]
DESCRIPTIONThis command is the CLI command for the tis_get_local_path function. This command searches for the localized file or directory and then prints the path to standard output. If the path is not found, the command returns nothing.
The wlocpath command uses the LANG environment variable to find the message catalog appropriate for the current language environment. For example, if
LANG=fr_FR
and
NLSPATH=/tivoli/msg_cat/%L/%N.cat;\
/tivoli/msg_cat/%L%N.cat;\
/tivoli/msg_cat/C/%N.cat
wlocpath will try the following path names to find the message catalog:
/tivoli/msg_cat/fr_FR/catalog_name.cat
/tivoli/msg_cat/fr/catalog_name.cat
/tivoli/msg_cat/C/catalog_name.cat
After the message is retrieved and bound, the resulting string is written to standard output.
Authorization
This command does not require any Tivoli Management Region (TMR) authorization roles to be executed.
Arguments
path Inputs the path string. If this string contains “%L”, it is substituted with the language name.
wlocpath
1–316 Version 3.7
–d default_path Identifies the default path. If the command to obtain the valid path from the path parameter fails, this parameter is used.
–l language Identifies the language name. If this parameter is not specified, the current LANG environment parameter is used.
–o output Identifies the name of the output file instead of writing to the standard output.
EXAMPLESThe following example looks for the file dodo.txt in the path ./msg_cat/%L.wlocpath ./msg_cat/%L/dodo.txt -d/tmp –l fr
The result will be what the LANG environment variable is for this file. If this variable is not found, the –d argument looks in the /tmp path. If the variable is still not found, the –l argument looks in the /fr path.
wlookup
Tivoli Management Framework Reference Manual 1–317
Com
mands
wlookup Searches for a resource instance in the Tivoli Name Registry.
SYNOPSISwlookup –l –R
wlookup –a [–L –o] –r resource_type
wlookup –r resource_type resource_name
wlookup –r resource_type –n instance_name {resource_name | –a}
DESCRIPTIONThe wlookup command searches a resource’s object information in the Tivoli name registry. If no type is specified, the default resource type is distinguished. If neither –L nor –o are specified, both the object identifier and label of the specified resource are returned. If –l and –R are specified, the time stamps for the modified resource types are listed.
Authorization
user, admin, senior, super
Arguments
–a Lists all instances of the specified resource type in the name registry.
–L Lists the label of the specified resource without its object identifier.
–l Lists the dates that the resource types were modified.
–n instance_name Looks up a nested resource under the specified instance.
–o Lists the object identifier of the specified resource without its label.
–R Displays a list of all resource types that are registered.
–r resource_type Specifies the resource type to be retrieved. If omitted, the default resource type is distinguished.
wlookup
1–318 Version 3.7
resource_name Specifies the name under which the resource is registered.
EXAMPLES
1. The following example looks up all distinguished resources in the Tivoli name registry:
wlookup -a
2. The following example displays a list of all registered resource types:
wlookup -R
3. The following example displays all instances of the policy region resource type:
wlookup -r PolicyRegion -a
4. The following example displays the object information for a particular instance (MyTask) of a resource type (TaskLibrary):
wlookup -r TaskLibrary MyTask
5. The following example displays the TaskExecute resources on managed node vail:
wlookup -r ManagedNode -n vail TaskExecute
SEE ALSOwregister
wls
Tivoli Management Framework Reference Manual 1–319
Com
mands
wls Lists a collection’s member objects.
SYNOPSISwls [–dlo] [path]
DESCRIPTIONThe wls command lists the members of the selected collection.
Authorization
You must have at least the user role in a group that the collection is a member of.
Arguments
–d Lists information about the collection itself, but not about the collection members.
–l Lists the object identifier and the label of each member.
–o Lists the object identifier of each member.
path Specifies the path to the collection object whose members are to be listed. Valid formats for the path argument include:
■ @ProfileManager:prof_manager_name
■ /Regions/PolicyRegionName/prof_manager_name
The default collection is the current working collection.
If the –l and –o arguments are omitted, this command lists only the members’ labels.
EXAMPLES
1. The following example lists the members of the current working collection:
wls
wls
1–320 Version 3.7
2. The following example lists the object identifiers and the labels of the members of the Administrators collection. This command is helpful in identifying administrators (or other objects) removed from the desktop but not deleted from the Tivoli database.
wls -l /Administrators
3. The following example lists the objects on administrator Jorge’s desktop:
wls @Administrator:jorge
SEE ALSOwcd, wpwd
wlsconn
Tivoli Management Framework Reference Manual 1–321
Com
mands
wlsconn Lists the current Tivoli Management Region (TMR) connections or information about a single connection, and completes the exchange of connection information if the connection process could not.
SYNOPSISwlsconn [TMR_name]
wlsconn –u region
DESCRIPTIONThe wlsconn command lists current TMR connection information including region number, port, connection mode, and resources and when they were last exchanged. If the –u argument is specified, wlsconn completes the exchange of connection information between the local TMR and the connected remote TMR. If no arguments are specified, wlsconn lists all current connections with the local TMR.
When exchanging resources between connected TMRs, it is useful to compare the output from the wlookup –l –R command to the output from the wlsconn command to determine which resources to update.
If the –u argument is specified, wlsconn completes the exchange of connection information if the connection process could not. If you use secure procedures to create a one-way connection in which the first side is the managing server and the second side is the managed server, you must use this command with the –u argument to exchange connection information.
Authorization
super if the –u argument is specified, otherwise user.
Arguments
–u region Updates the TMR name, remote server name, and other cached interregion information with the current information from the specified remote TMR.
TMR_name Specifies the name of the remote TMR.
wlsconn
1–322 Version 3.7
EXAMPLES
1. The following example lists all current connections to the local TMR:
wlsconnMODE NAME SERVER REGION<--> morie-Region morie 3333333333---> amon-sul-Region amon-sul 5555555555<--- ceridwen-Region ceridwen 2222222222
2. The following example lists the connection information for the connection between the local TMR and a TMR named morie-Region:
wlsconn morie-RegionName: morie-RegionServer:morieRegion:3333333333Mode:two_wayPort:94
Resource Name Last Exchange--------------- ---------------TMF_Notice Fri Jan 09 11:33:10 1998Administrator Fri Jan 02 13:13:15 1998PolicyRegion Tue Jan 13 10:00:38 1998TaskLibrary Tue Nov 04 10:02:34 1997Job Wed Dec 31 19:00:00 1969QueryLibrary Wed Dec 31 19:00:00 1969Query Wed Dec 31 10:00:00 1969ProfileManager Wed Nov 05 17:49:38 1997ManagedNode Tue Jul 07 19:24:34 1998Repeater Thu Sep 04 10:04:32 1997CheckDB Thu Sep 04 20:04:23 1997RemoveNode Thu Sep 04 20:04:23 1997HTTPRealm Tue Nov 04 20:03:22 1997HTTPRealmMakerGroup Thu Sep 04 20:07:22 1997HTTPRealmMaker Thu Sep 04 20:07:23 1997DependencyMgr Thu Sep 04 20:07:23 1997Gateway Wed Dec 31 19:00:00 1969Endpoint Wed Dec 31 19:00:00 1969
3. The following example exchanges connection information between the local TMR and a TMR named morie_Region:
wlsconn -u morie-Region
SEE ALSOwconnect, wdisconn, wlookup, wupdate
wlsendpts
Tivoli Management Framework Reference Manual 1–323
Com
mands
wlsendptsLists all the endpoints subscribed to a profile manager.
SYNOPSISwlsendpts [–l] profile_manager
DESCRIPTIONThe wlsendpts command lists all the endpoints directly or indirectly subscribed to the specified profile manager. The endpoints listed may be on the first subscription level (that is, profile manager to subscriber) or on any subscription level below that (such as profile manager to profile manager or profile manager to endpoint).
Authorization
user
Arguments
–l Prints the object ID of the endpoint as well as the endpoint label.
profile_manager Specifies the name of the profile manager for which you want a list of endpoints. Valid formats for the profile_manager argument include the following:
■ @prof_manager_name
■ @ProfileManager:prof_manager_name
■ /Regions/PolicyRegionName/prof_manager_name
EXAMPLESThe following example lists the endpoints subscribed to the Admin profile manager:wlsendpts "@ProfileManager:Admin PM"pepper (ManagedNode)gumby (ManagedNode)
wlsinst
1–324 Version 3.7
wlsinstLists the products and patches installed in a Tivoli Management Region (TMR).
SYNOPSISwlsinst {–a | –p | –P | –l | –s | –V name} [–ivh]
DESCRIPTIONThe wlsinst command lists the installed products, the installed patches, or both products and patches. Adding the optional –i, –v, or –h arguments includes host information with the product or patch list. The –s name argument searches for the specified product or patch. Product or patch names with spaces must be enclosed in quotation marks.
Authorization
super, senior, admin, or user
Arguments
–a Lists all products and patches installed in the TMR.
–p Lists all products installed in the TMR.
–P Lists all patches installed in the TMR.
–l Lists all the patches installed for those products that have been patched. If none of the products have been patched, no output is given.
–s name Lists the product or patch specified by name.
–V Prints out the path to each component, replacing any space at the end of the path name with a slash.
–i Sorts output by interpreter type. This argument must be used with either –v or –h.
–v Lists all host names, interpreter types, and the directories in which the various components (for example: binaries, libraries, or man pages) of each product or patch were installed.
wlsinst
Tivoli Management Framework Reference Manual 1–325
Com
mands
–h Lists the host name and interpreter type of the machines on which the products or patches are installed.
EXAMPLES
1. The following example lists all products and patches installed in the TMR:
wlsinst –a*---------------------------------------------------*
Product List*---------------------------------------------------*Tivoli Management PlatformTivoli/Admin 2.5*---------------------------------------------------*
Patch List*---------------------------------------------------*Tivoli Management Platform 3.0 Patch 3.0-TMP-0005Tivoli Management Platform 3.0 Service Pack 01
2. The following example lists only the products installed in the TMR:
wlsinst -p*---------------------------------------------------*
Product List*---------------------------------------------------*Tivoli Management PlatformTivoli/Admin 2.5
3. The following example lists the products installed, the host name and interpreter type on which each product was installed, and the directories in which each product was installed:
wlsinst -p -v*---------------------------------------------------*
Product List*---------------------------------------------------*Tivoli Management Platform
ida solaris2ALIDB /var/spool/Tivoli ida.dbAPPD /usr/lib/X11/app-defaultsBIN /usr/local/Tivoli/bin solaris2BIN /usr/local/Tivoli/bin solaris2BUN /usr/local/Tivoli/bin client_bundleCAT /usr/local/Tivoli/msg_catCONTRIB /usr/local/Tivoli/bin solaris2/contribGBIN /usr/local/Tivoli/bin generic_unixLIB /usr/local/Tivoli/lib solaris2
tornado solaris2
wlsinst
1–326 Version 3.7
APPD /usr/lib/X11/app-defaultsBIN /usr/local/Tivoli/bin solaris2CAT /usr/local/Tivoli/msg_catCONTRIB /usr/local/Tivoli/bin solaris2/contribDB /var/spool/Tivoli tornado.dbGBIN /usr/local/Tivoli/bin generic_unixLIB /usr/local/Tivoli/lib solaris2
wlsnotif
Tivoli Management Framework Reference Manual 1–327
Com
mands
wlsnotif Lists notices on an administrator’s bulletin board.
SYNOPSISwlsnotif [–g]
wlsnotif [–l] [–n ngroup [NID…]]
DESCRIPTIONThe wlsnotif command lists the notices on an administrator’s bulletin board. The –g argument directs wlsnotif to list all the notification groups. The –l argument directs wlsnotif to list only the headers of notices instead of the entire message. The –n argument directs wlsnotif to list notices only from a specified notice group. The list of notices can be limited to just those notices that match the notice identifiers specified by the NID… argument. The notice identifiers must follow the –g or –l argument. If –n is omitted, the notice data from all notice groups is listed. If no arguments are provided to wlsnotif, all notices from all notice groups are listed. The wlsnotif command restricts the notice groups to the subset of notice groups that the administrator subscribes to. In all cases, the output from this command is written to standard output.
Authorization
user, admin, senior, super
Arguments
–g Lists the valid notice groups, one per line. When this argument is used, it overrides the other arguments.
–l Lists the headers of the notices on the administrator’s bulletin board. If this argument is omitted, this command lists the actual notices.
–n ngroup [NID…] Specifies the notice group from which notices are to be listed or the specific notices to list. If this argument is omitted, this command lists notices from all notice groups.
wlsnotif
1–328 Version 3.7
EXAMPLES
1. The following example lists all notices from all notice groups. This output could be extremely long, so it should be redirected to a file.
wlsnotifNotice-id: 1Date: Mon Nov 21 10:29:12 1994Notice-Group-Name: Tivoli AdministrationPriority: NoticeSent-By-Administrator: root@bald
A new IP interface was added on bald by [email protected]: le1address: 146.84.49.3name: bald2
2. The following example lists all the notification groups to which the administrator is subscribed:
wlsnotif -gTivoli AdministrationTivoli AuthorizationTivoli DiagnosticsTivoli Scheduler
3. The following example lists the header of all messages on the administrator’s bulletin board:
wlsnotif -l#1 Mon Nov 21 10:29:12 A new IP interface was added onbald by#2 Mon Nov 21 10:30:25 An IP interface was deleted frombald by#3 Mon Nov 21 10:34:32 Deleted Objects#4 Mon Nov 21 10:37:08 A new task, date_task, wascreated by ro#5 Mon Nov 21 10:39:35 The task, date_task, of themy_tasks tas#6 Mon Nov 21 10:48:26 A new task, date_task2, wascreated by r#7 Mon Nov 21 10:49:33 The task, date_task2, of themy_tasks ta#8 Mon Nov 21 10:50:45 The task, date_task2, of themy_tasks ta#9 Mon Nov 21 10:55:52 A new task, find_cores, wascreated by r#10 Mon Nov 21 13:06:51 Created profile managermarketing.#11 Mon Nov 21 13:31:55 The job, date_job, wascreated by root@b
wlsnotif
Tivoli Management Framework Reference Manual 1–329
Com
mands
SEE ALSOwexpnotif, wsndnotif, wtailnotif
wlspol
1–330 Version 3.7
wlspol Lists available policy default and validation objects for a Tivoli managed resource type.
SYNOPSISwlspol [–d | –v] resource
DESCRIPTIONThe wlspol command lists the names of the policy default objects and policy validation objects for the specified managed resource type.
Authorization
senior, super
Arguments
–d Lists the labels of the policy default objects for the specified managed resource type. Policy default objects generate default attribute values for resources created in a policy region. This action is the default unless the –v argument is specified.
–v Lists the labels of the policy validation objects for the specified managed resource type. Policy validation objects validate attribute values for managed resources.
resource Specifies the managed resource type whose policy default objects or policy validation objects are to be listed.
EXAMPLESThe following example lists all the policy validation objects for the ProfileManager managed resource type. wlspol -v ProfileManager
SEE ALSOwcrtpr, wdelpr, wchkpol, wcrtpol, wdelpol, wgetdfpol, wgetpolm, wlspolm, wputpolm
wlspolm
Tivoli Management Framework Reference Manual 1–331
Com
mands
wlspolm Lists policy methods for a Tivoli managed resource type or lists attribute names for a profile.
SYNOPSISwlspolm [–d | –v] class
wlspolm [–d | –v] profile
DESCRIPTIONThe wlspolm class command lists the names of the policy methods assigned to the specified managed resource type class. The wlspolm profile command lists the attribute names (properties that can have policies associated with them) for the specified profile. The final option can be any managed resource type that supports policy methods (for example, a host, Network Information Services [NIS] domain, or file package) or a profile.
The names listed by this command can be used as input for the wgetpolm and wputpolm commands.
The –d argument lists default policies (default), and the –v argument lists validation policies. To set default and validation policies for specific Tivoli applications, see the application’s reference guide.
Authorization
senior or super
Arguments
–d Lists the policy default methods. This action is the default unless the –v argument is specified.
–v Lists the policy validation methods.
class Specifies the managed resource type whose policy methods are to be listed.
profile Specifies the profile whose attribute names are to be listed.
wlspolm
1–332 Version 3.7
EXAMPLESFor nonprofile usage:
The following example lists all the policy methods on a ProfileManager policy validation object: wlspolm -v ProfileManagerpm_val_remove_subscriberspm_val_remove_subscriptionpm_val_subscriberspm_val_subscription
For Configuration Change Management System (CCMS) profile usage:
The following command lists the properties that can have policies associated with them for the phone list profile named Engineering: wlspolm -d @PhoneListProfile:Engineeringnamephoneaddresscitystatecountrypostalownertypecomment
SEE ALSOwcrtpr, wdelpr, wchkpol, wcrtpol, wdelpol, wgetdfpol, wlspol, wputpolm
wlsrealms
Tivoli Management Framework Reference Manual 1–333
Com
mands
wlsrealmsLists the currently registered HTTP 1.0 authentication realms.
SYNOPSISwlsrealms
DESCRIPTIONThe wlsrealms command lists the currently registered HTTP 1.0 authentication realms.
Authorization
user, admin, senior, super
Arguments
None
EXAMPLESThe following example lists the currently registered HTTP 1.0 authentication realms:wlsrealms
SEE ALSOwaddrealm, wdelrealm, wstarthttpd, wstophttpd
wlssub
1–334 Version 3.7
wlssub Lists the profile managers to which an object, including a managed node, Network Information Services (NIS) domain, endpoint, or profile manager, subscribes.
SYNOPSISwlssub –l [–o]name
DESCRIPTIONThe wlssub command lists the profile managers to which a managed node, NIS domain, endpoint, profile manager, or other object subscribes.
Authorization
user, admin, senior, super
Arguments
–l Specifies a long listing.
–o Lists the object identifier for each profile manager to which an object subscribes. This object can include a managed node, an NIS domain, an endpoint, or a profile manager.
name Specifies the name of the object whose subscriptions are to be listed. Valid formats for the name argument include the following:
@domain_name@NisDomain:domain_name/Regions/PolicyRegionName/domain_name
EXAMPLESThe following example lists all the profile managers to which managed node cook subscribes. wlssub @ManagedNode:cook
wlssub
Tivoli Management Framework Reference Manual 1–335
Com
mands
SEE ALSOwcrtpr, wcrtprfmgr, wgetsub, wpopulate, wgetprf, wdistrib, wsub, wvalidate
wlstlib
1–336 Version 3.7
wlstlib Lists the contents of a task library.
SYNOPSISwlstlib library_name
DESCRIPTIONThe wlstlib command lists the contents of a task library.
Authorization
user, senior, super
Argument
library_name The name of the library to be listed.
EXAMPLESThe following example lists the contents of the queue_lib task library: wlstlib queue_libClean Queue (task)Clean Queue (job)
SEE ALSOwcrttlib
wmailhost
Tivoli Management Framework Reference Manual 1–337
Com
mands
wmailhostSpecifies the mail server used by Tivoli on Windows NT systems.
SYNOPSISwmailhost [host_name]
DESCRIPTIONThe wmailhost command provides an Simple Mail Transfer Protocol (SMTP) connection for Windows NT computers in the Tivoli environment. Issue wmailhost on any Windows NT computer that you add as a Tivoli Management Region (TMR) server or managed node. The Tivoli tools that generate e-mail send it to the mail server that you specify. Without the host_name argument, wmailhost prints the current mail server.
The mail server must be either an SMTP server or one connected with an SMTP gateway. For example, if the network mail server has Microsoft Exchange or Lotus Notes installed on a Windows NT computer, you must install SMTP gateway software on the computer. See “Windows NT Configuration for SMTP E-mail” in the Tivoli Enterprise Installation Guide for more information.
Arguments
host_name Specifies the host name of the mail server.
EXAMPLESThe following example sets the mail server to loki:wmailhost loki
wmannode
1–338 Version 3.7
wmannode Returns system information about a managed node in the Tivoli environment.
SYNOPSISwmannode node_name
DESCRIPTIONThe wmannode command returns system information about a managed node in the Tivoli environment. The managed node must be up and available when this command is run.
Authorization
user, admin, senior, super
Arguments
node_name Specifies the name of a managed node.
EXAMPLESThe following example lists the system information for managed node yankee: wmannode yankeeSystem Name : yankeeInterpreter : solaris2Install Directory : /usr/local/TivoliHost ID : 945bd30System Architecture : sun4mMemory Size (MB) : 48System Timezone : 360OS Name : SunOSOS Release : 5.3OS Version : Generic_101318-21
SEE ALSOwdiskspace, whostid, wident, winstdir, winterp, wmemsize, wtimezone
wmdist
Tivoli Management Framework Reference Manual 1–339
Com
mands
wmdistConfigures multiplexed distribution 2 (MDist 2) repeater parameters and manages distributions.
SYNOPSIS
Configuration Syntax
wmdist –s repeater_name [key=value...]
Distribution Syntax
wmdist –B [–A] [–f] repeater_name
wmdist [–f] –c distID
wmdist [–f] [–h] –d distID[distID…]
wmdist –D [debug_level]
wmdist –I repeater_name
wmdist –l [–i distID] [–a] [–v]
wmdist [–f] –p distID
wmdist [–f] –r distID
wmdist –R [rim_object]
wmdist –T [database_purge_interval]
Endpoint Status Syntax
wmdist –e distID [–t endpoint_label] [–n node_type][state...]
wmdist –q distID
DESCRIPTIONThe wmdist command provides MDist 2 repeater configuration and manages distributions. To configure the original MDist repeater system, see the wrpt command. If you have not configured a RIM database, you will only be able to use the –s and –I arguments.
Authorization
To cancel, delete, pause, or resume a distribution, you need either the senior authorization role or both the Dist_control authorization role and the RIM_view authorization role.
wmdist
1–340 Version 3.7
To change the level of log messages written by the distribution manager to its log file, configure the repeater with tuning parameters, change a RIM object to store status, or set the interval at which completed distributions are removed from the RIM database, you need the senior authorization role.
To display the internal state of the specified repeater and list distributions in the queue and connections in use, list endpoint status for a distribution, or display nodes associated with a given distribution in an indented format that indicates the route, you need either the senior authorization role or the RIM_view authorization role.
Configuration Arguments
–s Configures the repeater with the tuning parameters (key=value).
repeater_name Specifies the name of the repeater site.
repeater_name can be one of the following:
■ Label, or object ID of the gateway or managed node of a repeater
■ default
Note: The default setting for a new repeater.
■ all
Note: All repeaters including the default setting.
wmdist
Tivoli Management Framework Reference Manual 1–341
Com
mands
key=value Enables you to specify a tuning parameter keyword and a value for the keyword. Tuning parameter keywords are as follows:
rpt_dir=pathname Specifies the parent directory used to hold the depot directory and the states directory. The depot directory contains all the segments stored in the database and must have enough free space to hold the value of disk_max. The states directory contains the database that holds the persistent state of the repeater’s queue.
permanent_storage=TRUE | FALSE Configures the repeater to be a depot. If TRUE, the depot will retain segments marked for permanent storage by applications after their distribution finishes. If FALSE, a distribution’s segments are deleted after the repeater finishes sending the distribution to all its targets.
max_sessions_high=number Specifies the maximum number of concurrent connections a repeater will open for high-priority distributions. These connections are shared among all active distributions. If the repeater runs out of high-priority connections, it tries to use a medium-priority connection.
wmdist
1–342 Version 3.7
max_sessions_medium=number Specifies the maximum number of concurrent connections a repeater will open for medium-priority distributions. These connections are shared among all active distributions. If the repeater runs out of medium-priority connections, it tries to use a low-priority connection.
max_sessions_low=number Specifies the maximum number of concurrent connections a repeater will open for low-priority distributions. This number must one or greater. These connections are shared among all active distributions. If the repeater runs out of low-priority connections, it waits for an open connection to complete before opening additional connections.
disk_max=max_size_MB Specifies the amount of disk space allocated to the repeater depot. Units are in Mbytes. If the disk_max number equals zero, no limit will be enforced. This number cannot exceed the size of the disk. Every distribution flowing through a repeater is stored at least temporarily in the depot. The depot must be large enough to hold the largest distribution that you expect to distribute.
wmdist
Tivoli Management Framework Reference Manual 1–343
Com
mands
mem_max=max_size_MB Specifies the amount of memory used to buffer data being sent to targets. This improves performance by reducing the number of disk accesses to the depot. The memory is shared among all active distributions. Units are in Mbytes.
send_timeout=seconds Specifies the timeout used to detect a network or target failure while sending data. A target is allowed send_timeout seconds to receive each packet on the network. If a timeout occurs, the distribution remains in the repeaters queue and a retry occurs in conn_retry_interval seconds.
execute_timeout=seconds Specifies the amount of time an endpoint method has to return results after it has received all of a distribution’s data. Some applications may be running scripts after receiving data but before returning results to the repeater. Units are in seconds.
wmdist
1–344 Version 3.7
notify_interval=minutes Specifies the frequency (in minutes) of status reporting. As targets finish, their results are buffered by the repeater. When the notify_interval has elapsed or all of the targets of this distribution have finished, the results are flushed. The results are sent to the application using MDist 2 and updated in the MDist 2 database.
conn_retry_interval=seconds Specifies the frequency (in
seconds) that unavailable or interrupted targets will be retried.
retry_ep_cutoff=seconds Specifies the amount of time (in seconds) to continue retrying an unavailable or interrupted endpoint. Unavailable or interrupted repeaters are retried until the distribution’s deadline has been reached.
net_load=KB_per_second Specifies the maximum amount of network bandwidth the repeater is allowed to use. Units are in kilobytes per second. This allocation is shared among all active distributions. Used with target_netload.
wmdist
Tivoli Management Framework Reference Manual 1–345
Com
mands
target_netload=KB_per_second Specifies the maximum amount of network bandwidth that can be sent to an individual target. Units are in kilobytes per second. The default value of 0 disables this check. Used with net_load.
packet_size=number Specifies the number of bytes written to the network during each send.
debug_level=number Controls the number of log messages written to the managed node repeater’s log files ($DBDIR/rpt2log). Logging for the gateway repeater is controlled with the debug_level set with the wgateway command.
When no key=value pairs are listed, the wmdist –s command returns the configurations currently in use. The following is example output:
repeater_id: 1589385886.1.560rpt_dir:D:/Tivoli/20000215/db/jachtermann1.db/tmppermanent_storage: TRUEmax_sessions_high: 5max_sessions_medium: 10max_sessions_low: 40disk_max: 500 (MB)mem_max: 64 (MB)send_timeout: 300 (secs)execute_timeout: 600 (secs)notify_interval: 30 (mins)conn_retry_interval: 900 (secs)retry_ep_cutoff: 7200 (secs)net_load: 100 (KB/sec)packet_size: 16 (KB)target_netload: 0 (KB/secdebug_level: 3
wmdist
1–346 Version 3.7
Note: The listed values are the default values for a UNIX repeater. The default repeater directory for Windows NT is $DBDIR/tmp.
Changes to the following parameters are not effective until the repeater is restarted:
■ rpt_dir
■ max_sessions_high (if the new value is greater than the old)
■ max_session_medium (if the new value is greater than the old)
■ max_session_low (if the new value is greater than the old)
■ disk_max (if the new value is greater than the old)
■ mem_max (if the new value is greater than the old)
Distribution Arguments
–a Returns active distributions only.
–A Deletes all entries from a repeater’s depot. Since you must delete a repeater’s queue before its depot, you must always use the –A argument with the –B argument. Use this command only if instructed to by your Tivoli Service Provider.
–B Deletes all entries from a repeater’s queue. Use this command only if instructed to by your Tivoli Service Provider.
–c Cancels a distribution with the ID specified by distID.
–d Deletes a distribution from the MDist 2 database. The distribution is specified by the distID.
wmdist
Tivoli Management Framework Reference Manual 1–347
Com
mands
–D [debug_level] Changes the level of log messages written by the distribution manager to its log file, $DBDIR/distmgr.log. Valid numbers are from 0 through 9. Higher numbers print more information. The default value is 0. This file continues to grow until cleaned up by the user. Issuing this command without a value prints the current value.
–f Forces the operation. Without the –f argument, the wmdist command prompts the user for confirmation.
–h Forces the removal from the database of distributions that have not completed.
–i Specifies the distribution ID. When no distribution is specified, the wmdist command returns statuses for all distributions.
–I Displays the internal state of the specified repeater, and lists distributions in the queue and connections in use. The following is sample output:
Repeater: 1713721474.1.593Jobs in SEND queue: 2Jobs in RECEIVE queue: 0=== Session Information ===Low: available = 40 used = 0Medium: available = 10 used = 0High: available = 5 used = 0=== Distribution Information ===Id: 1713721474941664856Label: mftp_testPriority: 3Application: Mftp
–l Lists distribution status.
–n Filters output to only show repeaters or endpoints.
–p Pauses a distribution.
–r Resumes a distribution.
–R [rim_object] Allows the user to change the RDBMS Interface Module (RIM) object used by the distribution manager to store status. The default value is mdist2. Issuing this command without a value prints the current value.
wmdist
1–348 Version 3.7
–T [database_purge_interval] Sets the interval at which completed distributions will be removed from the RIM database. Setting this interval allows the distribution manager to automatically remove completed distributions from the database and prevent the database from running out of space. Issuing this command without a value prints the current value.
The units for database_purge_interval are seconds. Setting database_purge_interval to -1 disables database purges. The default value is -1.
–v If present, the wmdist command returns all information about the status. If –v is not specified, the wmdist command returns key information only.
endpoint_label Specifies the endpoint by its label.
Endpoint Status Arguments
–e Lists endpoint status for a distribution.
–t Specifies endpoints of the distribution. If endpoints are specified, the wmdist command lists status of these endpoints only. Otherwise, it lists statuses of all endpoints.
–q Displays the nodes associated with a given distribution in an indented format that indicates the route. Each node displayed is suffixed with its state.
state Lists statuses for nodes (endpoints and repeaters) in the specified states. If not specified, the wmdist command lists statuses for all nodes. The supported states are as follows:
■ WAITING
■ PAUSED
■ UNAVAILABLE
■ RECEIVING
■ INTERRUPTED
■ SENDING
■ SUCCESSFUL
wmdist
Tivoli Management Framework Reference Manual 1–349
Com
mands
■ FAILED
■ CANCELLED
■ EXPIRED
■ READY
■ REJECTED
EXAMPLES
1. The following example sets permanent_storage to FALSE and the disk_max to 51200 for all repeaters, including the default configuration:
wmdist -s all permanent_storage=FALSE disk_max=51200
2. The following example lists complete information about all active distributions:
wmdist -l -a -v
3. The following example lists statuses of all endpoints in state WAITING and PAUSED:
wmdist -e WAITING PAUSED
SEE ALSOwrpt, wdepot
wmdistgui
1–350 Version 3.7
wmdistguiStarts the multiplexed distribution 2 (MDist 2) graphical user interface from the managed node on which this command is run.
SYNOPSISwmdistgui
DESCRIPTIONThe MDist 2 graphical user interface must be installed on the managed node prior to running the command. To run this command on a UNIX machine, you must enable connections to the X Window System on the UNIX machine. You must also ensure that remote logins are enabled.
Authorization
You must have either the senior or RIM_view authorization role to view the status.
Arguments
This command does not take any arguments.
wmemsize
Tivoli Management Framework Reference Manual 1–351
Com
mands
wmemsize Reports the amount of physical memory installed on a managed node.
SYNOPSISwmemsize node_name
DESCRIPTIONThe wmemsize command reports the amount of physical memory installed on a managed node in the Tivoli installation. The managed node must be up and available.
The command’s output is the number of megabytes of physical memory in the machine. The command writes the memory size to its standard output.
Authorization
user, admin, senior, super
Arguments
node_name Specifies the name of the managed node on which to report.
EXAMPLESThe following example displays the amount of memory installed on ebbets. wmemsize ebbets64
wmerge
1–352 Version 3.7
wmerge Performs a three-way file merge.
SYNOPSIS wmerge [–L label1 [–L label3]] [–p] [–q] “file1 file2 file3”
DESCRIPTIONThe wmerge command incorporates all changes that lead from file2 to file3 into file1. The result goes to standard output if –p is present, into file1 otherwise. wmerge is useful for combining separate changes to an original. Suppose file2 is the original, and both file1 and file3 are modifications of file2. wmerge combines both changes.
An overlap occurs if both file1 and file3 have changes in a common segment of lines. On a few older hosts where diff3 does not support the –E argument, wmerge does not detect overlaps, and merely supplies the changed lines from file3. On most hosts, if overlaps occur, wmerge outputs a message (unless the –q argument is given), and includes both alternatives in the result. The alternatives are delimited as follows:
<<<<<<< “file1”“lines in file1”“=======”“lines in file3”>>>>>>> “file3”
If there are overlaps, the user should edit the result and delete one of the alternatives. If the –L “label1” and –L “label3” arguments are given, the labels are output in place of the names file1 and file3 in overlap reports.
DIAGNOSTICSExit status is 0 for no overlaps, 1 for some overlaps, 2 for many overlaps.
SEE ALSOwrcsmerge, wco
wmerge
Tivoli Management Framework Reference Manual 1–353
Com
mands
AUTHORAuthor: Walter F. Tichy. Revision Number: 1.1.6.2; Release Date: 1993/10/07. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991 by Paul Eggert.
wmrgaef
1–354 Version 3.7
wmrgaefMerge custom dialogs into Tivoli Management Framework or a Tivoli application after upgrading.
SYNOPSISwmrgaef [–r resource…] –d path
DESCRIPTIONThe wmrgaef command merges Tivoli Management Framework or Tivoli application custom dialogs after an upgrade. You must first save the custom dialogs with the wcatcher command.
The wmrgaef command attempts to merge the custom dialog with the upgraded dialog. The more similar the original and the upgraded dialogs, the easier it is to merge the custom dialog.
If the original and upgraded dialogs are completely different, it is possible that the merge may produce invalid Dialog Specification Language (DSL). In this case, wmrgaef indicates that it was unable to merge that dialog. It saves the original dialog, the upgraded dialog, and the merged attempt in the directory specified with the wcatcher command.
Authorization
super
Arguments
–r resource Specifies a resource type to merge. If you do not specify a resource type, wmrgaef reads all the custom dialogs in the specified directory and tries to merge them.
–d path Specifies the path to the file containing the custom dialogs (the output of the wcatcher command). This includes both the path and the name of the directory where the custom dialog resides.
wmrgaef
Tivoli Management Framework Reference Manual 1–355
Com
mands
EXAMPLESThe following example merges custom dialogs saved in /tmp/aef/my.dir:wmrgaef -d /tmp/aef/my.dir
SEE ALSOwcatcher
wmrgini
1–356 Version 3.7
wmrgini Merges groups and variables from one .INI file into another. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwmrgini dest_file merge_file
DESCRIPTIONThe wmrgini command merges the contents of one .INI file in another. For each variable in merge_file, the command creates or replaces an identical variable in dest_file.
Arguments
dest_file Specifies the name of the destination file.
merge_file Specifies the name of the file to merge.
EXAMPLESTo merge the SYSTEM.INI file into the WIN.INI file, enter the following:wmrgini C:\TEMP\WIN.INI C:\TEMP\SYSTEM.INI
SEE ALSOweditini
wmv
Tivoli Management Framework Reference Manual 1–357
Com
mands
wmv Moves objects between collections.
SYNOPSISwmv [–I] label… collection
DESCRIPTIONThe wmv command moves the specified objects from the current working collection into the specified collection. Both of this command’s arguments can be full or partial label paths.
If you use this command to move an endpoint, run the wep sync_gateways command to synchronize the endpoint data stored by the endpoint manager, gateways, and endpoints within the Tivoli Management Region (TMR).
Authorization
admin, senior, or super in the policy region where the resource is moving
Arguments
–I Ignores all failed suboperations, allowing the command to continue. This argument is useful only when multiple labels are passed to the command. The –I argument allows a move process to fail for individual objects, but the command continues to the next object to be moved. Without this argument, if a move process fails for an individual object, the command will restore any objects already removed and then the command will fail. The default is for the command to fail when a suboperation fails.
label… Specifies the labels of one or more objects to be moved. This argument can be a full label path (starting at the ‘/’ collection), partial label path (relative to the current working collection), or simple name (to be found in the current working collection).
wmv
1–358 Version 3.7
collection Specifies the label of the destination collection. This argument can be a full label path (starting at the ‘/’ collection), a partial label path (relative to the current working collection), or a simple name (to be found in the current working collection). The default is the current working collection. The linked objects become members of the selected collection.
EXAMPLESThe following example moves the ManagedNode object ceridwen from the lost-n-found collection into the desktop collection for administrator Root. wmv /lost-n-found/ceridwen /Administrators/Root_ceridwen-region
SEE ALSOwln, wep
wpatch
Tivoli Management Framework Reference Manual 1–359
Com
mands
wpatch Installs a Tivoli patch.
SYNOPSISwpatch [–c src_dir] [–i patch] [–n] [–y] [install_variables] [managed_node…]
DESCRIPTIONThe wpatch command installs a Tivoli patch from the command line when invoked on the Tivoli Management Region (TMR) server.
Authorization
install_product
Arguments
–c src_dir Specifies the complete path to the installation image.
–i patch Specifies the patch index (.IND) file to install. You must specify the file name in all capital letters. You can enter the file name with or without the file extension. For example, if the source directory contains the file TMF.IND, specifying either –i TMF or –i TMF.IND indicates the correct index file.
–n Installs the patch on all managed nodes that do not currently have the patch installed. This argument is ignored if a managed node is specified.
–y Specifies that the installation should proceed without confirmation. By default, wpatch identifies the actions that must be taken to perform the installation and requests confirmation before continuing. Using this argument, wpatch identifies the actions and performs the installation without requesting the confirmation.
wpatch
1–360 Version 3.7
install_variables Specifies product-specific keyword=value pairs. This argument generally is not used except to override a previous installation of the patch. To force any directory or other installation variable to be overwritten, enter an exclamation mark (!) as the value for the specified variable. For example, to reinstall the binaries, you would enter BIN=! instead of entering the entire path to the binaries directory.
managed_node Specifies the managed node on which a Tivoli patch will be installed. Multiple managed nodes can be specified. If no managed nodes are specified, the patch is installed on all managed nodes in the TMR. In most cases, this argument will not be specified.
SEE ALSOwserver, wclient, winstall
wping
Tivoli Management Framework Reference Manual 1–361
Com
mands
wping Attempts to contact the object dispatcher on a host.
SYNOPSISwping host_name [timeout]
DESCRIPTIONThe wping command attempts to contact the object dispatcher on the specified host. If the target host’s object dispatcher responds, this command prints the following to standard output: object dispatcher on host_name is alive
If the target host’s object dispatcher does not respond, this command prints the following to standard output: no response from object dispatcher on host_name
Authorization
user, admin, senior, super
Arguments
host_name The name of the host to be contacted.
timeout The number of seconds to wait for the host to reply before reporting that the host is inactive.
EXAMPLESThe following example shows the status of the object dispatcher on managed node bald: wping baldobject dispatcher on bald is alive
SEE ALSOwdate, wdiskspace, whostid, wifconfig, winstdir, winterp, wmannode, wtimezone, wuname, wxterm
wpopulate
1–362 Version 3.7
wpopulate Populates a profile from system files.
SYNOPSISwpopulate [–o] source name
DESCRIPTIONThe wpopulate command adds existing configuration information from a system managed by Tivoli to a configuration profile.
This command populates the profile identified by name based on the configuration found in a profile endpoint, such as a host or Network Information Services (NIS) domain. The source argument identifies the profile endpoint from which to populate. The type of information with which the profile is populated depends on the profile type of name. For example, if name is a user profile, it will be populated with users from the specified host’s passwd file (or the specified NIS domain’s password map).
If –o is specified, the wpopulate command overwrites the current profile contents. If –o is not specified, the contents from source are appended to the profile contents.
Authorization
senior, super
Arguments
–o Specifies to overwrite the specified profile’s current contents.
source Specifies the name of the profile endpoint from which to populate.
name Specifies the name of the profile to populate.
EXAMPLESThe following example populates the Users profile with the contents of the passwd file on pinatubo. The content of the file will be appended to the Users profile. wpopulate @ManagedNode:pinatubo @UserProfile:Users
wpopulate
Tivoli Management Framework Reference Manual 1–363
Com
mands
SEE ALSOwcrtprf, wcrtprfmgr, wgetsub, wlssub, wgetprf, wdistrib, wsub, wunsub, wxterm
wputeppol
1–364 Version 3.7
wputeppolReplaces an endpoint policy script that has been modified.
SYNOPSISwputeppol pol_name
DESCRIPTIONThe wputeppol command replaces an endpoint policy script. After the script has been modified, this command saves the changes by writing the script to the Tivoli database. Script contents must be entered through standard input.
Arguments
pol_name Specifies the name of the policy script to be replaced.
Authorization
senior
EXAMPLESThe following example saves changes made to the login policy script by writing the policy script to the database:wputeppol login_policy < login_policy
SEE ALSOwgeteppol
wputpolm
Tivoli Management Framework Reference Manual 1–365
Com
mands
wputpolm Replaces a policy method’s body.
SYNOPSISwputpolm [–C | –c value] [–d | –v] class name policy
wputpolm [–d | –v] [–F | –N] [–n | –C | –c value] [args=a1,…] profile policy
DESCRIPTIONThe wputpolm command replaces the body of the specified policy method. There are two forms for the wputpolm command; the form for replacing a policy method of a traditional tivoli managed resource, and the form for replacing the value of a policy on a profile.
In the first form, the class argument specifies the type of resource, and name specifies the label of the policy object on which to act. If the –d argument is specified, name specifies a policy default object name and default policy for the resource.
This form of the command can be used to define the policy method in one of two ways. It can read from its standard input the body of the policy method. In this form, wputpolm is intended for defining methods that are implemented as shell scripts. However, this form also works on binary files and accepts an executable program from the standard input. The command can also define a policy method that has a constant value. In this form, it is not necessary to write a shell script. These constant methods require less storage space and execute more quickly than shell-script methods. The command can read the constant return value either from the command line, using the –c value argument, or from standard input, if the –C argument is specified.
In the second form of the command, the profile argument specifies the profile name, and the policy argument specifies the individual attribute whose policy to set, as returned by the wlspolm command. The –C, –c, –d, and –v arguments behave identically for profiles and managed resources and can be used to install constant- or script-valued policies on a profile. When running wputpolm on a profile, the –n argument is also available. The –n argument indicates none. Used with –d for a default policy, –n means that there is no default value for the individual
wputpolm
1–366 Version 3.7
attribute. Used in conjunction with –v for a validation policy, –n indicates that any value is valid for the policy.
The –F and –N arguments are used to set the policy to be fixed or not fixed, respectively. If neither flag is specified, the fixed status of the policy is left unchanged.
The optional args list is valid only for script-valued policies, and identifies the input options to pass to the policy script. For any input arguments of the form $attribute, where attribute is the name of an attribute of the resource type, the attribute value is passed as input to the script.
Authorization
For the first form of the command, super and policy
For the second form of the command, senior or super
Arguments
–C Specifies that the policy method is defined always to return the specified constant value read from this command’s standard input. If this argument and the –c argument are omitted, this command reads the method’s body from standard input.
–c value Specifies that the policy method is defined always to return the specified constant value. value is an alphanumeric American National Standard Code for Information Interchange (ASCII) string. Numeric values are read and stored as strings. If this argument and the –C argument are omitted, this command reads the method’s body from standard input.
–d Specifies that the method is a default policy.
–F Specifies that the policy is fixed and the subscribers cannot override it.
–N Specifies that the policy is not fixed. After distribution, subscribers can override the policy.
–n Specifies that either there is no default value for the attribute of the policy or any value is valid for the policy.
wputpolm
Tivoli Management Framework Reference Manual 1–367
Com
mands
–v Specifies that the method is a validation policy.
class Specifies the managed resource type to which the policy is assigned.
name Specifies the name of the managed resource.
policy Specifies the name of the method whose body is to be defined or replaced.
profile Specifies the profile to which the policy is assigned.
args=al… Specifies additional arguments to the method.
Input
If the –C argument is present, this command reads from the command’s standard input the constant return value to be set for the policy method.
If the –c argument is present, this command ignores its standard input.
If the –C and –c arguments are both omitted, this command reads the body of the method (usually a shell script) from the command’s standard input.
EXAMPLESFor nonprofile usage:
The following command installs a new policy script for the pm_val_subscribers method of the Restricted policy validation object for PolicyManager. The script is read from standard input. wputpolm -v ProfileManager Restricted pm_val_subscribers < \new_script
The following command sets the policy for pm_val_subscribers to be the constant TRUE, which means that all subscribers are accepted: wputpolm -v -c TRUE ProfileManager Restricted \pm_val_subscribers
wputpolm
1–368 Version 3.7
For profile usage:
The following command installs a new default policy script for user ID (UID) generation for the user profile named Engineering. The policy is fixed so that subscribers cannot override it. The script takes the user’s real name and login name as its arguments. The script is read from standard input. wputpolm -d -F args=’$real_name,$login_name’ \@UserProfile:Engineering uid < new_script
SEE ALSOwcrtpr, wdelpr, wchkpol, wcrtpol, wdelpol, wgetdfpol, wgetpolm, wlspol, wlspolm
wpwd
Tivoli Management Framework Reference Manual 1–369
Com
mands
wpwd Displays the current working collection.
SYNOPSISwpwd [–o]
DESCRIPTIONThe wpwd command displays the label of the administrator’s current working collection for the current parent process ID. Each administrator has a separate current working collection associated with each parent process ID.
Authorization
user, admin, senior, super
Argument
–o Displays the collection’s object ID. If this argument is omitted, this command displays the collection’s label.
EXAMPLESThe following example displays the label of the current working collection: wpwd
SEE ALSOwcd
wrcs
1–370 Version 3.7
wrcs Changes Revision Control System (RCS) file attributes.
SYNOPSISwrcs [arguments] file …
DESCRIPTIONThe wrcs command creates new RCS files or changes attributes of existing ones. An RCS file contains multiple revisions of text, an access list, a change log, descriptive text, and some control attributes. For wrcs to work, the caller’s login name must be on the access list, except if the access list is empty, the caller is the owner of the file or the super user, or the –i argument is present.
Paths matching an RCS suffix denote RCS files; all others denote working files. Names are paired as explained in wci. Revision numbers use the syntax described in wci.
Arguments
–i Creates and initializes a new RCS file, but does not deposit any revision. If the RCS file has no path prefix, tries to place it first into the subdirectory ./RCS, and then into the current directory. If the RCS file already exists, prints an error message.
–a logins Appends the login names appearing in the comma-separated list logins to the access list of the RCS file.
–A oldfile Appends the access list of oldfile to the access list of the RCS file.
–e [logins] Erases the login names appearing in the comma-separated list logins from the access list of the RCS file. If logins is omitted, erases the entire access list.
–b [rev] Sets the default branch to rev. If rev is omitted, the default branch is reset to the (dynamically) highest branch on the trunk.
wrcs
Tivoli Management Framework Reference Manual 1–371
Com
mands
–c string Sets the comment leader to string. An initial wci, or a wrcs –i without –c, guesses the comment leader from the suffix of the working file name.
This argument is obsolescent, because RCS normally uses the preceding $Log$ line’s prefix when inserting log lines during checkout (see wco). However, older versions of RCS use the comment leader instead of the $Log$ line’s prefix, so if you plan to access a file with both old and new versions of RCS, make sure that its comment leader matches its $Log$ line prefix.
–k subst Set the default keyword substitution to subst. The effect of keyword substitution is described in wco. Giving an explicit –k argument to wco, wrcsdiff, and wrcsmerge overrides this default. Do not use wrcs –kv, because –kv is incompatible with wco –l. Use wrcs –kkv to restore the normal default keyword substitution.
–l [rev] Locks the revision with number rev. If a branch is given, locks the latest revision on that branch. If rev is omitted, locks the latest revision on the default branch. Locking prevents overlapping changes. A lock is removed with wci or wrcs –u.
–u [rev] Unlocks the revision with number rev. If a branch is given, unlocks the latest revision on that branch. If rev is omitted, removes the latest lock held by the caller. Normally, only the locker of a revision may unlock it. Somebody else unlocking a revision breaks the lock. This causes a mail message to be sent to the original locker. The message contains a commentary solicited from the breaker. The commentary is terminated by end-of-file or by a line containing ‘.’ by itself.
–L Sets locking to strict. Strict locking means that the owner of an RCS file is not exempt from locking for check in. This argument should be used for files that are shared.
wrcs
1–372 Version 3.7
–U Sets locking to non-strict. Non-strict locking means that the owner of a file need not lock a revision for check in. This argument should not be used for files that are shared. Whether default locking is strict is determined by your system administrator, but it is normally strict.
–m rev:msg Replaces revision rev’s log message with msg.
–M Does not send mail when breaking somebody else’s lock. This argument is not meant for casual use; it is meant for programs that warn users by other means and invoke wrcs –u only as a low-level lock-breaking operation.
–n name[:[rev]] Associates the symbolic name name with the branch or revision rev. Deletes the symbolic name if both : and rev are omitted; otherwise, prints an error message if name is already associated with another number. If rev is symbolic, it is expanded before association. A rev consisting of a branch number followed by a ‘.’ stands for the current latest revision in the branch. A : with an empty rev stands for the current latest revision on the default branch, normally the trunk. For example, wrcs –n name: RCS/* associates name with the current latest revision of all the named RCS files; this contrasts with wrcs–n name: RCS/*, which associates name with the revision numbers extracted from keyword strings in the corresponding working files.
–N name[:[rev]] Acts like –n, except overrides any previous assignment of name.
wrcs
Tivoli Management Framework Reference Manual 1–373
Com
mands
–o range Deletes (“outdates”) the revisions given by range. A range consisting of a single revision number means that revision. A range consisting of a branch number means the latest revision on that branch. A range of the form rev1:rev2 means revisions rev1 to rev2 on the same branch, :rev means from the beginning of the branch containing rev up to and including rev, and rev: means from revision rev to the end of the branch containing rev. None of the outdated revisions may have branches or locks.
–q Runs quietly; does not print diagnostics.
–I Runs interactively, even if the standard input is not a terminal.
–sstate[:rev] Sets the state attribute of the revision rev to state. If rev is a branch number, assumes the latest revision on that branch. If rev is omitted, assumes the latest revision on the default branch. Any identifier is acceptable for state. A useful set of states is Exp (for experimental), Stab (for stable), and Rel (for released). By default, wci sets the state of a revision to Exp.
–t [file] Writes descriptive text from the contents of the named file into the RCS file, deleting the existing text. The file path name may not begin with –. If file is omitted, obtains the text from standard input, terminated by end-of-file or by a line containing ‘.’ by itself. Prompts for the text if interaction is possible; see –I. With –i, descriptive text is obtained even if –t is not given.
–t - string Writes descriptive text from string into the RCS file, deleting the existing text.
wrcs
1–374 Version 3.7
–T Preserves the modification time on the RCS file unless a revision is removed. This argument can suppress extensive recompilation caused by a make dependency of some copy of the working file on the RCS file. Use this argument with care; it can suppress recompilation even when it is needed, that is, when a change to the RCS file would mean a change to keyword strings in the working file.
–V Prints RCS’s version number.
–V n Emulates RCS Version n. See wco for details.
–x suffixes Uses suffixes to characterize RCS files. See wci for details.
–z zone Uses zone as the default time zone. This argument has no effect; it is present for compatibility with other RCS commands.
At least one explicit argument must be given to ensure compatibility with future planned extensions to the wrcs command.
Compatibility
The -b rev argument generates an RCS file that cannot be parsed by RCS Version 3 or earlier.
The -k subst arguments (except -k kv) generate an RCS file that cannot be parsed by RCS Version 4 or earlier.
Use wrcs -V n to make an RCS file acceptable to RCS Version n by discarding information that would confuse version n.
RCS Version 5.5 and earlier does not support the -x argument and requires a ,v suffix on an RCS path name.
FILESwrcs accesses files much as wci does, except that it uses the effective user for all accesses, it does not write the working file or its directory, and it does not read the working file unless a revision number of $ is specified.
wrcs
Tivoli Management Framework Reference Manual 1–375
Com
mands
ENVIRONMENT
RCSINIT Arguments prepended to the argument list, separated by spaces. See wci for details.
DIAGNOSTICSThe RCS path name and the revisions outdated are written to the diagnostic output. The exit status is zero if and only if all operations were successful.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.13; Release Date: 1995/06/05. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991, 1992, 1993, 1994, 1995 by Paul Eggert.
wrcs
1–376 Version 3.7
SEE ALSOwco, wci, wident, wrcsdiff, wrcsmerge, Walter F. Tichy, RCS—A System for Version Control, Software—Practice & Experience 15, 7 (July 1985), 637-654.
BUGSA catastrophe (for example, a system crash) can cause RCS to leave behind a semaphore file that causes later invocations of RCS to claim that the RCS file is in use. To fix this, remove the semaphore file. A semaphore file’s name typically begins with , or ends with _.extensions to the wrcs command.
The separator for revision ranges in the –o argument used to be – instead of :, but this leads to confusion when symbolic names contain –. For backward compatibility, wrcs –o still supports the old – separator, but it warns about this obsolete use.
Symbolic names need not refer to existing revisions or branches. For example, the –o argument does not remove symbolic names for the outdated revisions; you must use –n to remove the names.
wrcsdiff
Tivoli Management Framework Reference Manual 1–377
Com
mands
wrcsdiff Compares Revision Control System (RCS) revisions.
SYNOPSISwrcsdiff [–k subst] [–q] [–r rev1 [–r rev2]] [–T] [–V n] [–x suffixes] [–z zone] [diff_arguments] file …
DESCRIPTIONThe wrcsdiff command runs diff to compare two revisions of each RCS file given.
Paths matching an RCS suffix denote RCS files; all others denote working files. Names are paired as explained in wci.
The argument –q suppresses diagnostic output. Zero, one, or two revisions may be specified with –r. The argument –k subst affects keyword substitution when extracting revisions, as described in wco; for example, –k k–r1.1–r1.2 ignores differences in keyword values when comparing revisions 1.1 and 1.2. To avoid excess output from locker name substitution, –k kvl is assumed if (1) at most one revision argument is given, (2) no –k argument is given, (3) –k kv is the default keyword substitution, and (4) the working file’s mode would be produced by wco –l. See wco for details about –T, –V, –x, and –z. Otherwise, all arguments of diff that apply to regular files are accepted, with the same meaning as for diff.
If both rev1 and rev2 are omitted, wrcsdiff compares the latest revision on the default branch (by default the trunk) with the contents of the corresponding working file. This is useful for determining what you changed since the last check in.
If rev1 is given, but rev2 is omitted, wrcsdiff compares revision rev1 of the RCS file with the contents of the corresponding working file.
If both rev1 and rev2 are given, wrcsdiff compares revisions rev1 and rev2 of the RCS file.
Both rev1 and rev2 may be given numerically or symbolically.
wrcsdiff
1–378 Version 3.7
EXAMPLESThe following command compares the latest revision on the default branch of the RCS file to the contents of the working file f.c:
wrcsdiff f.c
SEE ALSOwco, wci, wident, wrcsdiff, wrlog, Walter F. Tichy, RCS—A System for Version Control, Software—Practice & Experience 15, 7 (July 1985), 637-654.
ENVIRONMENT
RCSINIT Arguments prepended to the argument list, separated by spaces. See wci for details.
DIAGNOSTICSExit status is 0 for no differences during any comparison, 1 for some differences, 2 for many differences.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.5; Release Date: 1993/11/03. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991, 1992, 1993 by Paul Eggert.
wrcsmerge
Tivoli Management Framework Reference Manual 1–379
Com
mands
wrcsmerge Merges Revision Control System (RCS) revisions.
SYNOPSISwrcsmerge [options] file
DESCRIPTIONThe wrcsmerge command incorporates the changes between two revisions of an RCS file into the corresponding working file.
Paths matching an RCS suffix denote RCS files; all others denote working files. Names are paired as explained in wci.
At least one revision must be specified with one of the arguments described below, usually –r. At most two revisions may be specified. If only one revision is specified, the latest revision on the default branch (normally the highest branch on the trunk) is assumed for the second revision. Revisions may be specified numerically or symbolically.
wrcsmerge prints a warning if there are overlaps, and delimits the overlapping regions as explained in merge. The command is useful for incorporating changes into a checked-out revision.
Arguments
–k subst Uses subst style keyword substitution. See wco for details. For example, –kk–r1.1–r1.2 ignores differences in keyword values when merging the changes from 1.1 to 1.2.
–p [rev] Sends the result to standard output instead of overwriting the working file.
–q [rev] Runs quietly; does not print diagnostics.
–r [rev] Merges with respect to revision rev. Here an empty rev stands for the latest revision on the default branch, normally the head.
–V n Emulates RCS version n. See wco for details.
–x suffixes Uses suffixes to characterize RCS files. See wci for details.
wrcsmerge
1–380 Version 3.7
EXAMPLES
1. Suppose you have released revision 2.8 of f.c. Assume furthermore that after you complete an unreleased revision 3.4, you receive updates to release 2.8 from someone else. To combine the updates to 2.8 and your changes between 2.8 and 3.4, put the updates to 2.8 into file f.c and execute the following command:
wrcsmerge –p –r2.8 –r3.4 f.c >f.merged.c
Then examine f.merged.c. Alternatively, if you want to save the updates to 2.8 in the RCS file, check them in as revision 2.8.1.1 and execute wco –j:
wci –r2.8.1.1 f.c
wco –r3.4 –j2.8:2.8.1.1 f.c
2. As another example, the following command undoes the changes between revision 2.4 and 2.8 in your currently checked out revision in f.c:
wrcsmerge –r2.8 –r2.4 f.c
Note the order of the arguments and that f.c will be overwritten.
SEE ALSOwco, wci, wident, wrcsdiff, wrcsmerge, wrlog, Walter F. Tichy, RCS—A System for Version Control, Software—Practice & Experience 15, 7 (July 1985), 637-654.
ENVIRONMENT
RCSINIT Arguments prepended to the argument list, separated by spaces. See wci for details.
DIAGNOSTICSExit status is 0 for no overlaps, 1 for some overlaps, 2 for many overlaps.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.3; Release Date: 1991/08/19. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991 by Paul Eggert.
wrefresh
Tivoli Management Framework Reference Manual 1–381
Com
mands
wrefresh Refreshes a Tivoli collection window.
SYNOPSISwrefresh collection
DESCRIPTIONThe wrefresh command refreshes the collection window of the specified collection.
Authorization
user
Arguments
collection Specifies which collection window will be refreshed. To refresh the Administrators window, use the following format:
/Administrators/administrator_name
To refresh other collection windows, use one of the following formats:
/Regions/top_level_region_name/subregion_name@NisDomain:domain_name
EXAMPLES
1. The following example refreshes every instance of administrator Callahan’s desktop. If multiple Callahan desktops are open, all will be refreshed.
wrefresh /Administrator/Callahan
2. The following example refreshes all instances of the New York policy region:
wrefresh @PolicyRegions:NewYork
wregister
1–382 Version 3.7
wregister Registers a new resource instance with the name registry.
SYNOPSISwregister –i [–f n] –r resource_type wregister [–i [–f n] –r resource_type] name object wregister –u [–r resource_type] name
DESCRIPTIONThe wregister command registers a new resource instance with the Tivoli name registry. The command optionally initializes the cache for a new resource type. If –r is not specified, the default is distinguished.
Authorization
senior, super
Arguments
–i Initializes the resource cache. If this argument is not specified and the specified resource type does not already exist in the cache, wregister generates an error.
–f n Specifies that the resource type being created should be nonexchangeable. Nonexchangeable resource types cannot be updated between connected Tivoli Management Regions (TMRs).
–r resource_type Specifies the resource type of the resource to be registered. If omitted, the default resource type is distinguished.
–u Removes a resource from a resource type.
name Specifies the name under which the resource is to be registered.
object Specifies the object reference of the resource.
wregister
Tivoli Management Framework Reference Manual 1–383
Com
mands
EXAMPLES
1. The following example adds a new resource type, MyResource, to the name registry. The new resource type will be nonexchangeable.
wregister -i -f n -r MyResource
2. The following example adds a resource called mylabel to MyResource. The object ID for mylabel is 400004.34.26.
wregister -r MyResource mylabel 400004.34.26
3. The following example removes the resource mylabel from MyResource.
wregister -r MyResource -u mylabel
4. The following example adds a new resource type, YourResource, and adds a resource named yourlabel to YourResource. The object ID of yourlabel is 400005.35.37.
wregister -i -r YourResource yourlabel 400005.35.37
SEE ALSOwlookup
wrestart
1–384 Version 3.7
wrestart Initiates a system restart and optional reboot. This command should be run from an endpoint. (Windows NT only)
SYNOPSISwrestart [–b] [–c] [–f] [–t timeout_value] [–m “confirm_message”]
DESCRIPTIONThe wrestart command initiates an operating system restart and optional machine reboot.
Arguments
–b Reboots the system after shutdown.
–c Prompts the user for confirmation before restarting the system or rebooting.
–f Forces a reboot and restart in spite of unsaved changes in other applications. This argument does not cause applications to display message boxes prompting users to save their changes.
–m “confirm_message” Specifies the confirmation message that will be displayed.
–t timeout_value Specifies the number of seconds this command waits for user confirmation before initiating a restart.
EXAMPLES
1. To prompt the user for confirmation before restarting the system, enter the following command:
wrestart -c
2. To display a warning message before restarting the system in 60 seconds, enter the following command:
wrestart -m "WARNING: The system will reboot in 60 \seconds!!" -t 60
wrimtest
Tivoli Management Framework Reference Manual 1–385
Com
mands
wrimtestVerifies an RDBMS Interface Module (RIM) object’s connectivity and functionality.
SYNOPSISwrimtest [–l RIM_object_label]
DESCRIPTIONThe wrimtest command is an interactive command-line utility that enables you to connect to a specified database and execute RIM methods. If you do not specify the –l argument, the default RIM object is inventory. Use the wlookup -ar RIM command to view a list of available RIM objects.
Authorization
rim_view, rim_update
Arguments
–l RIM_object_label Specifies the RIM object you want to test. The wrimtest command connects to the database specified by RIM_object_label. A prompt enables you to enter one of the following command options:
c: RIM_commit Commits a transaction.
d: RIM_delete Deletes a row from the database.
e: RIM_execute_sql Executes a Structured Query Language (SQL) statement.
g: RIM_retrieve_rows Retrieves rows from the database.
i: RIM_insert_rows Inserts a row into the database.
r: RIM_rollback Cancels a transaction.
wrimtest
1–386 Version 3.7
u: RIM_update_rows Updates rows in the database.
?: Help List Prints a list of command options.
x: Exit Exits the wrimtest utility.
EXAMPLESThe following example lists the attribute values for the tec RIM object. Following the list, the user is prompted for a command option.wrimtest -l tecResourceType:RIMResource Label:tecHost Name:lynxUser Name:tecVendor:SybaseDatabase:tecDatabase Home:/data/sybaseServer ID:tecInstance Home:Opening Regular Session…Session OpenedRIM : Enter Option >
SEE ALSOwrimtrace
wrimtrace
Tivoli Management Framework Reference Manual 1–387
Com
mands
wrimtraceEnables or disables tracing for RDBMS Interface Module (RIM) objects.
SYNOPSISwrimtrace RIM_object_label [INFORMATION | ERROR | TRACE_OFF]
DESCRIPTIONThe wrimtrace command enables or disables tracing for RIM objects. The contents of the Inter-Object Message (IOM) packets passed between the RIM object and client program and relational database management system (RDBMS) errors are printed to the RIM log file located in /tmp/rim_db_log. You can locate and change the default location of the RIM log file by following these steps:
1. Run the following command:
odadmin environ get > env.out
2. Edit the env.out file and add the following:
RIM_DB_LOG=/tivoli/rim/rim_db_log
3. Run the following command:
odadmin environ set < env.out
Executing the wrimtrace command without the trace_level option prints the current trace level to standard output. The tracing function is intended for debugging purposes. If enabled for extended periods of time, tracing can decrease performance and slow the processing of RIM calls considerably.
Note: When you change the RIM tracing level, you must manually locate and terminate the appropriate RIM_database_prog or RIM_database_Agent process on your machine. RIM processes include the following:
Oracle RIM_Oracle_prog and RIM_Oracle_Agent
Sybase RIM_Sybase_prog
DB2 RIM_DB2_prog
Microsoft SQL RIM_MS_SQL_prog
wrimtrace
1–388 Version 3.7
Arguments
RIM_object_label Specifies the RIM object you want to trace.
Choose one of the following trace levels:
ERROR Prints RDBMS errors to the RIM log file.
INFORMATION Prints the contents of IOM packets to the RIM log file.
TRACE_OFF Turns tracing off.
EXAMPLES
1. The following example prints the current trace level of the Tivoli Inventory RIM object:
wrimtrace inventory
2. The following example prints IOM packet information to the RIM log file:
wrimtrace inventory INFORMATION
3. The following example prints IOM packet information and RDBMS errors to the RIM log file:
wrimtrace inventory "INFORMATION|ERROR"
4. The following example turns RIM tracing off:
wrimtrace inventory TRACE_OFF
SEE ALSOwrimtest
wrlog
Tivoli Management Framework Reference Manual 1–389
Com
mands
wrlog Prints log messages and other information about Revision Control System (RCS) files.
SYNOPSISwrlog [arguments] file …
DESCRIPTIONThe wrlog command prints information about RCS files.
Paths matching an RCS suffix denote RCS files; all others denote working files. Names are paired as explained in wci.
wrlog prints the following information for each RCS file: RCS path name, working path name, head (for example, the number of the latest revision on the trunk), default branch, access list, locks, symbolic names, suffix, total number of revisions, number of revisions selected for printing, and descriptive text. This is followed by entries for the selected revisions in reverse chronological order for each branch. For each revision, wrlog prints revision number, author, date and time, state, number of lines added or deleted (with respect to the previous revision), locker of the revision (if any), and log message. All times are displayed in Coordinated Universal Time (UTC). Without arguments, wrlog prints complete information. The following arguments restrict this output.
Arguments
–L Ignores RCS files that have no locks set. This is convenient in combination with –h, –l, and –R.
–R Prints only the name of the RCS file. This is convenient for translating a working path name into an RCS path name.
–h Prints only the RCS path name, working path name, head, default branch, access list, locks, symbolic names, and suffix.
–t Prints the same information as –h, timeout plus the descriptive text.
wrlog
1–390 Version 3.7
–b Prints information about the revisions on the default branch, normally the highest branch on the trunk.
–d dates Prints information about revisions with a check-in date and time in the ranges given by the semicolon-separated list of dates. A range of the form d1<d2 or d2>d1 selects the revisions that were deposited between d1 and d2 inclusive. A range of the form <d or d> selects all revisions dated d or earlier. A range of the form d< or >d selects all revisions dated d or later. A range of the form d selects the single, latest revision dated d or earlier. The date and time strings d, d1, and d2 are in the free format explained in wco. Quoting is normally necessary, especially for < and >. Note that the separator is a semicolon.
–l [lockers] Prints information about locked revisions only. In addition, if the comma-separated list lockers of login names is given, ignores all locks other than those held by lockers. For example, wrlog –L –R –l wft RCS/* prints the name of RCS files locked by the user wft.
–r [revisions] Prints information about revisions given in the comma-separated list, revisions, of revisions and ranges. A range rev1:rev2 means revisions rev1 to rev2 on the same branch, :rev means revisions from the beginning of the branch up to and including rev, and rev: means revisions starting with rev to the end of the branch containing rev. An argument that is a branch means all revisions on that branch. A range of branches means all revisions on the branches in that range. A branch followed by a ‘.’ means the latest revision in that branch. A bare –r without revisions means the latest revision on the default branch, normally the trunk.
–s states Prints information about revisions whose state attributes match one of the states given in the comma-separated list states.
–w [logins] Prints information about revisions checked in by users with login names appearing in the comma-separated list logins. If logins is omitted, the user’s login is assumed.
wrlog
Tivoli Management Framework Reference Manual 1–391
Com
mands
–V n Emulates RCS version n when generating logs. See wco for more details.
–x suffixes Uses suffixes to characterize RCS files. See wci for details.
wrlog prints the intersection of the revisions selected with the arguments –d, –l, –s, and –w, intersected with the union of the revisions selected by –b and –r.
EXAMPLES
1. The following command prints the names of all RCS files in the subdirectory RCS that have locks:
wrlog -L -R RCS/*
2. The following command prints the headers of those
files:wrlog -L -h RCS/*
3. The following command prints the headers plus the log messages of the locked revisions:
wrlog –L –l RCS/*
4. The following command prints complete information:
wrlog RCS/*
ENVIRONMENT
RCSINIT Arguments prepended to the argument list, separated by spaces. See wci for details.
DIAGNOSTICSThe exit status is zero if, and only if, all operations were successful.
AUTHORAuthor: Walter F. Tichy. Revision Number: 5.3; Release Date: 1991/08/22. Copyright © 1982, 1988, 1989 by Walter F. Tichy. Copyright © 1990, 1991 by Paul Eggert.
wrlog
1–392 Version 3.7
SEE ALSOwco, wci, wident, wrcs, wrcsdiff, wrcsmerge, wrlog, Walter F. Tichy, RCS—A System for Version Control, Software—Practice & Experience 15, 7 (July 1985), 637-654.
BUGSThe separator for revision ranges in the –r argument used to be – instead of :, but this leads to confusion when symbolic names contain –. For backward compatibility, wrlog –r still supports the old – separator, but it warns about this obsolete use.
wrm
Tivoli Management Framework Reference Manual 1–393
Com
mands
wrm Removes objects from a collection.
SYNOPSISwrm [–I] label…
DESCRIPTIONThe wrm command removes the specified objects from the collection. label can be a label or a label path. This command removes only references to objects; it does not delete the objects themselves.
Authorization
admin, senior, super
Arguments
–I Ignores all failed suboperations, allowing the command to continue. This argument is useful only when multiple labels are passed to the command. The –I argument allows a removal operation to fail for individual objects, but the command continues to the next object to be removed. Without this argument, if a remove operation fails for an individual object, the command will restore any objects already removed, and then the command will terminate with an error. The default is for the command to fail when the suboperation fails.
label… Specifies the labels of or label paths to the objects to be removed. Objects are specified similarly to UNIX file names. If a label path (full or relative) is specified, the object is removed from the collection that the label path names; that is, the object is removed from the collection named by the label path less its final component. If only the unadorned object label is specified, the object is removed from the current working collection.
wrm
1–394 Version 3.7
EXAMPLESThe following example removes the ManagedNode object ceridwen from the Administrators collection. The object itself is not removed. wrm /Administrators/Root_ceridwen-region/ceridwen
SEE ALSOwdel
wrmnode
Tivoli Management Framework Reference Manual 1–395
Com
mands
wrmnode Removes a managed node from a Tivoli installation.
SYNOPSISwrmnode [–f] node_name [–d dispatcher_number] [node_name [–d dispatcher_number]]…
DESCRIPTIONThe wrmnode command removes the specified managed node from the Tivoli database. For a UNIX managed node, this command shuts down the dispatcher, and then removes the node from the Tivoli database.
Managed nodes are specified by name. If a managed node has been damaged, it may be necessary to provide the dispatcher number. This number can be obtained by using the odadmin odlist command.
This command will not remove the Tivoli Management Region (TMR) server.
After using wrmnode, you may want to verify the database with the wchkdb command. This will ensure that there are no references to the node.
Authorization
install-client, super
Argument
–f Performs all requested removals without requiring confirmation from the user.
node_name Specifies the name of the managed node to be removed.
–d dispatcher_number Shuts down the specified dispatcher and removes a damaged managed node.
NOTESThis command does not remove the Tivoli executables, databases, and other files from the affected managed node.
wrmnode
1–396 Version 3.7
EXAMPLES
1. The following example removes the managed node sherman from the Tivoli database:
wrmnode sherman
2. The following example removes a partially installed or partially removed node. The dispatcher number must be provided because the node name is not fully known to the system. To determine the dispatcher number, enter the following:
odadmin odlist
Region Disp Flags Port IPaddr Hostname(s)2323231 ct- 737 146.84.25.15 ceridwen,ceridwen.tivoli.com2 -t- 737 146.84.29.12 elcap,elcap.tivoli.com
To remove the partially installed or partially removed node, enter the following:
wrmnode elcap -d 2
SEE ALSOodadmin, wchkdb, wbkupdb, winstall, wpatch, wserver, wclient
wrplblk
Tivoli Management Framework Reference Manual 1–397
Com
mands
wrplblkReplaces a block of statements in a file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwrplblk [–r] –s “start_string” –e “end_string” [–o output_file] {–i “replace_string” | @filename} filename
DESCRIPTIONThe wrplblk command replaces a block of statements in a file. This command is intended to replace a block of statements that are clearly delimited at the beginning and end of the block (such as those added using the winsblk command).
Arguments
–e “end_string” Specifies a search string that signifies the end of the block of statements. You must surround the string with double quotation marks.
–i {“replace_string” | @filename} Specifies a string to replace the text between the delimited statements, or a file containing a block of statements. You must surround the string with double quotation marks.
–o output_file Writes the output of this command to the output_file file, instead of standard output.
–r Replaces the delimiter lines in addition to the block of statements.
–s “start_string” Specifies a search string that signifies the start of the block of statements. You must surround the string with double quotation marks.
filename Specifies the file in which to replace the block of statements.
wrplblk
1–398 Version 3.7
EXAMPLESTo replace a block of statements beginning with [boot] and ending with end in the SYSTEM.INI file with statements in the RPLBLK.FIL file, enter the following command:wrplblk -s "[boot]" -e "end" -o C:\TEMP\OUTPUT.FIL \-i @C:\TEMP\RPLBLK.FIL C:\WINDOWS\SYSTEM.INI
The output of this command is redirected to the OUTPUT.FIL file.
SEE ALSOwinsblk, wclrblk
wrplline
Tivoli Management Framework Reference Manual 1–399
Com
mands
wrpllineReplaces a single line in a file. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwrplline [–f] –s “search_string” [–o output_file] –r “replace_string” filename
DESCRIPTIONThe wrplline command replaces a line in a text file. The line to be replaced is found using a search string. Output from this command is written to standard output.
Arguments
–f Processes only the first occurrence of the search string. If this argument is not specified, the command processes each occurrence of the search string.
–o output_file Writes the output of this command to the output_file file, instead of standard output.
–r “replace_string” Specifies a string to replace the line that contained the search string. You must surround the string with double quotation marks.
–s “search_string” Specifies a search string. If the search string is contained in a line, the line is replaced with the string specified by the –r argument. You must surround the string with double quotation marks.
filename Specifies the name of the file in which to replace the line.
wrplline
1–400 Version 3.7
EXAMPLESTo replace every occurrence of a line beginning with device= in the SYSTEM.INI file with the type= string, enter the following command:wrplline -s "device=" -o C:\TEMP\OUTPUT.FIL -r "type=" \C:\WINDOWS\SYSTEM.INI
The output of this command is written to the OUTPUT.FIL file.
SEE ALSOwclrline, winsline
wrpt
Tivoli Management Framework Reference Manual 1–401
Com
mands
wrpt Modifies the repeater system.
SYNOPSIS
Configuration Syntax
wrpt [–g] [–e]
wrpt [–T [seconds]]
wrpt [–n] name [wan | nowan] [default | nodefault] [always | noalways] [range=value]
wrpt [–r] name
Tuning Syntax
wrpt [–k id] –t name [reinit | key_val=value…]
Active Distribution Syntax
wrpt –L
wrpt –R –k id
wrpt –A [–f] –k id
Query Syntax
wrpt –q source_host name [name…]
DESCRIPTIONThe wrpt command is used to display, configure, and monitor multiplexed distribution (MDist). MDist is the repeater system that Tivoli uses to distribute data from profile-based applications and the Tivoli Software Distribution application.
The configuration syntax statements are used to list, add, delete, and modify repeater sites.
The –t argument in the tuning syntax statement displays and changes tuning parameters for individual repeater sites.
The active distribution syntax allows you to list or modify active distributions.
wrpt
1–402 Version 3.7
The –q argument is a query argument that returns the repeater route for debugging or verifying the distribution path.
The name option specifies the name of a host (managed node). Host numbers are the same as those in the Disp column of the output from odadmin odlist.
Note: The wrpt command cannot add or delete Tivoli endpoints to a gateway’s range. The gateway range is dynamically set as endpoints log into gateways or are deleted from gateways.
Authorization
senior
Configuration Arguments
When no arguments are listed, wrpt returns a table that contains all repeater sites. The first column is the host name (with the host number in square brackets [ ]); the second column indicates that the site is a default repeater (d) or a wide area network (WAN) entry site (w); and the third column lists the range of hosts served by the repeater.
Note: The resulting table shows only the managed nodes in a repeater’s range. Endpoints are not listed.
–g Changes the format to match the input argument format of the wrpt add or change arguments. This makes it easier to capture a repeater layout to restore later.
–e Lists the range of endpoints served by the repeater.
–n name Creates a new or modifies an existing repeater site, where name is the name of the managed node.
–T [seconds] Specifies the repeater manager timeout. This timeout value is the maximum time (in seconds) that a repeater node will wait after a distribution for final processing on the target to complete before an error is forced to terminate the connection. A final timeout value of 0 indicates no, or infinite, timeout.
wrpt
Tivoli Management Framework Reference Manual 1–403
Com
mands
wan Specifies this repeater site as the WAN entry point for the region. All distributions from other regions will be routed through this site. If you do not specify a WAN entry point for the Tivoli Management Region (TMR), any repeater can be the first hop of an interregion distribution. Use nowan to turn off this argument.
nowan Turns off the wan option.
default Indicates that this repeater will serve all hosts that are not explicitly listed in another repeater’s range. Use nodefault to turn off this option.
nodefault Turns off the default option.
always Specifies that distributions go through this repeater although the repeater has only one client. By default, if a repeater has only one client, a distribution to that client goes directly to the client, bypassing the repeater. The always option overrides the default behavior. Use the noalways option to turn off the always option and revert to default behavior.
noalways Turns off the always option.
range=value Specifies a comma-separated list of host numbers; a run of consecutive numbers may be abbreviated with a - (for example, 2–14 would be an inclusive list of host numbers 2 through 14). Tivoli does not check ranges. If you create conflicting or overlapping ranges, unexpected results can occur.
–r name Removes the specified repeater site.
Tuning Arguments
–k When used as a tuning option, –k causes configuration options to affect only the active distributions.
Note: When used as an active distribution option (with the –R and –A arguments), –k specifies the target active process.
wrpt
1–404 Version 3.7
id Specifies the unique process number of an active distribution, obtained with the –L argument and used with the –k argument.
–t Displays and changes tuning parameters for individual repeater sites.
name Specifies the host (managed node) as it is registered in the Tivoli name registry.
reinit Resets all parameters to the factory default.
key_val=value Enables you to specify a tuning parameter keyword (listed below) and a value (either an integer or an absolute path name for a directory) for the keyword. If value is not specified, the existing parameters for the specified site are displayed. Tuning parameter keywords are as follows:
disk_dir Specifies the directory used for temporary paging, or swap, space. Note that the repeater must be configured with adequate swap space to avoid hung distributions. This swap space must be at least as large as disk_max.
disk_hiwat Specifies the disk usage (in KB) at which a delay occurs between disk block allocations. The delay period is specified by the disk_time tuning parameter keyword. A disk block allocation is 16 KB. Tivoli recommends that this value equal about 50 percent of the maximum disk space available to the repeater.
wrpt
Tivoli Management Framework Reference Manual 1–405
Com
mands
disk_max Specifies the maximum amount of disk space (in KB) to use for paging. You will need to set the disk_max and mem_max options dependent on the type of repeater you are distributing through. For nongateway repeaters, mem_max plus disk_max should at least equal the size of the largest file package distributed if max_conn is less than the number of clients that are targets of the distribution. For gateway repeaters, only the disk_max option should be set to a value at least equal to the size of the largest file package distributed if max_conn is less than the number of clients that are targeted by the distribution.
disk_time Specifies the delay (in seconds) between disk block allocations. The delay starts only after disk usage rises above the number indicated by the disk_hiwat tuning parameter keyword.
max_conn Specifies the maximum number of simultaneous parallel client connections initiated by the repeater during a distribution.
mem_max Specifies the maximum memory (in KB) to be used before paging to disk. You will need to set the disk_max and mem_max options dependent on the type of repeater you are distributing through. For nongateway repeaters, mem_max plus disk_max should at least equal the size of the largest file package distributed if max_conn is less than the number of clients that are targets of the distribution. For gateway repeaters, only the disk_max option should be set to a value at least equal to the size of the largest file package distributed if max_conn is less than the number of clients that are targeted by the distribution.
wrpt
1–406 Version 3.7
net_load Specifies the maximum amount of data (in KB per second) that the repeater will send to the network for each distribution. Tivoli recommends that this value equal about 25 percent of the network bandwidth (between repeater and clients). Note that you cannot set net_load to a value that is greater than 32 MB/sec. Also, if you specify a negative number for net_load, the parameter is set per target machine rather than per distribution.
net_spacing Specifies a delay (in milliseconds) to insert between each write to the network.
stat_intv Specifies a high-level Transmission Control Protocol (TCP) timeout (in seconds) after which an error terminates the blocked connection. This value is dependent on the network client machines’ processors, particularly the PC processors and RAM.
Active Distribution Arguments
–L Lists all active distributions in a four-column format. The first column is the unique active distribution number, the second column is the distribution name (a label chosen by the application), the third column is the distribution’s start time, and the fourth column gives statistics for the distribution in the following format: in/est_size [out_min-out_max].
–R Shows the repeater route.
–k When used as an active distribution option (with the –R and –A arguments), specifies the target active process.
Note: When used as a tuning option, –k causes configuration options to affect only the active distributions.
wrpt
Tivoli Management Framework Reference Manual 1–407
Com
mands
id Specifies the unique process number of an active distribution, obtained with the –L argument and used with the –k argument.
–A Aborts a distribution. The user is prompted Are you sure? unless the force argument (–f) is also given.
–f Forces an operation (suppresses any confirmation prompt).
Query Arguments
–q Returns the distribution route. This argument can be used to verify that a route will be as you expect before you begin distributions.
source_host Specifies the name of the source host for the distribution.
name […name] Specifies the host (managed node) as it is registered in the Tivoli name registry.
EXAMPLES
1. The following example returns the list of all repeater sites in the TMR:
wrptfuji [1] wd [default]palomar [2]
--[2-14,18,20-40]
The first output column contains the host names followed by the host numbers in square brackets [ ]. The first entry in the second column can be a w or a –. A w indicates that the entry is a WAN entry site. If the second entry in the second column is a d, the entry is the default repeater site. The third column contains the range of hosts served by the repeater. If you specify the –g argument, the format will be changed to match the input argument format of the wrpt add or change arguments. This makes it easier to capture a repeater layout to restore later.
wrpt
1–408 Version 3.7
2. The following example creates a new repeater site:
wrpt -n palomar range=2-14,18,20-40
where:
–n palomar Specifies host palomar as the new repeater site.
range=2-14,18,20-40 Specifies the host numbers that will be in the distribution range for the new repeater site. The host numbers include 2 through 14, 18, and 20 through 40.
3. The following example changes the maximum network load that this repeater site can add to 100 KB/sec:
wrpt -k -t chaos net_load=100
4. The following example gets the unique process number for an active distribution, calls that distribution using its number, and changes the maximum network load that the process can add to 100 KB/sec. This command changes the network load only for this distribution. To set the network load for a repeater site, see example 3.
wrpt -Ll fp_distribute Jun 16 12:53:27 1696/1696 [0-432]wrpt -k l -t chaos net_load=100
where:chaos is the name of the host (managed node) that the repeater is configured on.
wrunas
Tivoli Management Framework Reference Manual 1–409
Com
mands
wrunasRuns a given command as a given user. The password for the user is retrieved from the registry using a given key.
SYNOPSISwrunas [user_name | key | command]
DESCRIPTIONThe wrunas command retrieves the password from the registry, uses the Microsoft authentication package, and launches a given command. The wrunas command can be used in a Task Library script or an Application Extension Facility (AEF) method script to launch executables from the Tivoli desktop.
Arguments
command Specifies the command to be executed.
key Specifies the key that stores the password for the user_name.
user_name Specifies the username.
EXAMPLESThe following example retrieves the password for Administrator when the key is admin_key.wrunas Administrator admin_key net config workstation
wruninvquery
1–410 Version 3.7
wruninvqueryQueries the database for inventory information and returns a list of object IDs and object labels of machines that match the query criteria.
SYNOPSISwruninvquery [–i] [–T idl_type] [–l | –t] query_name [input…]
DESCRIPTIONThe wruninvquery command runs a query and returns a list of object IDs and object labels in a format that can be used for a subscription list. The output of all queries is a SysAdminTypes_ObjectLabelList. To use this command, the columns TME_OBJECT_ID and TME_OBJECT_LABEL must be included in the columns list of the query. If these columns are not included in the query, or if you want to simply display query output in text format, use the wrunquery command.
The wruninvquery command returns only the following output:
■ A line-separated list of object IDs (the default)
■ A line-separated list of object labels
■ An American National Standard Code for Information Exchange (ASCII) Interface Definition Language (IDL)-encoded version of an instance of SysAdminTypes_ObjectLabelList
This command can also read a limited set of inputs that can narrow the query results. If input is provided, the query combines the results of the query with the input, and then returns only the results that are found in both lists. Input types are accepted in the following formats:
■ A list of object IDs (the default) separated by spaces.
■ An ASCII representation of an IDL type. Currently, the only IDL types that are valid input are the following:
• SysAdminTypes_ObjectList
• SysAdminTypes_ObjectLabelList
• TMF_CCMS_subscriber_list
wruninvquery
Tivoli Management Framework Reference Manual 1–411
Com
mands
Authorization
Query_execute, admin, senior, or super
Arguments
–i Reads query input, either object IDs or an ASCII representation of the IDL data type, from standard input. If the –T argument is not specified, the input is interpreted as a space-separated list of object IDs. If the –T argument is specified, the input must be an ASCII representation of the IDL data type (similar to that used by the idlcall and idlattr commands). Input can come from either standard input or the command line, but not both.
–T idl_type Specifies the full name of an IDL data type. The input, whether coming from standard input or the command line, must be an ASCII representation of the IDL type.
–l Specifies that the output should be a new line-separated list of object labels.
–t Specifies that the output should be an ASCII representation of the IDL result as output.
query_name Specifies the name of the query to run.
input… Specifies the input to the query. If the –T argument is not specified, the input is interpreted as a space- separated list of object IDs. If the –T argument is specified, the input must be an ASCII representation of the IDL data type (similar to that used by the idlcall and idlattr commands). Input can come from either standard input or the command line, but not both.
wruninvquery
1–412 Version 3.7
EXAMPLES
1. The following example runs the AIX-machines query and prints the output as a list of object IDs:
wruninvquery AIX-machines
The output is as follows:
1922582407.1.323#TMF_ManagedNode::Managed_Node#555555.1.332#TMF_ManagedNode::Managed_Node#
2. The following example runs the AIX-machines query and prints the output as a list of object labels:
wruninvquery -l AIX-machines
The output is as follows:
manzanoamon-sul
3. The following example runs the AIX-machines query and prints the output as an ASCII-encoded representation of the SysAdminTypes_ObjectLabelList type:
wruninvquery -t AIX-machines
The output is as follows:
{ 2 { 1922582407.1.323#TMF_ManagedNode::Managed_Node# \"manzano" } { 555555.1.332#TMF_ManagedNode::Managed_Node# \"amon-sul" } }
4. The following example runs the AIX-machines query, using the subscribers of the pm1 profile manager, and produces a list of labels for the output:
idlcall 555555.1.535#TMF_CCMS::ProfileManager# \_get_subscribers | wruninvquery -l -i \-T TMF_CCMS::subscriber_list aix-boxes amon-sul
The output is as follows:
manzano
Use the wrunquery command instead of the wruninvquery command if you want to simply display the results of a query, or if the query does not include the TME_OBJECT_ID and TME_OBJECT_LABEL columns.
wruninvquery
Tivoli Management Framework Reference Manual 1–413
Com
mands
SEE ALSOidlattr, idlcall, wcrtqlib, wcrtquery, wgetquery, wrunquery, wsetquery
wrunjob
1–414 Version 3.7
wrunjob Runs a job in a task library.
SYNOPSISwrunjob job_name –l library [–a argument] [–e name=value] [–iEr] [–T transtype]
DESCRIPTIONThe wrunjob command runs a job that exists in a task library.
Authorization
You must have the role specified when the job was created. You can use the wgetjob command to find the required role.
Arguments
job_name Specifies the name of the job to be run.
–l library Specifies the task library containing the task to be run.
–a argument Specifies the argument to be passed to the task. If the argument to be passed includes an option flag and an argument, enclose both in quotation marks (for example, –a “o argument”).
–e name=value Sets an environment variable for the task (for example, DISPLAY=bald:0.0).
–i Reads input arguments for the task from standard input.
–E Passes to the task all environment variables set on the user’s system.
-r Returns an error code of 1 if at least one endpoint fails to execute its job properly
wrunjob
Tivoli Management Framework Reference Manual 1–415
Com
mands
–T transtype Specifies a transaction type. See “Tivoli Transactions” on page 1-6 for additional information about transaction types. This argument can be one of the following:
top Top-level transaction. This is the default if the –T argument is not specified.
sub Subtransaction.
revoke Revocable transaction.
none No transaction.
EXAMPLES
1. The following example runs job date_job, which is contained in task library my_tasks.
wrunjob date_job -l my_tasks###################################################Task Name: date_taskManaged Node: baldReturn Code: 0-------Standard Output-------Mon Nov 21 14:24:16 CST 1998-------Standard Error Output-------####################################################
2. The following example executes job date_job, which is contained in task library my_tasks. The LANG environment variable is set to German.
wrunjob date_job -l my_tasks -e LANG=de#####################################################Task Name: date_taskManaged Node: baldReturn Code: 0-------Standard Output-------Montag, 21. November 1998 14:25:30 Uhr CST-------Standard Error Output-------#####################################################
wrunjob
1–416 Version 3.7
3. The following example runs the job ps_vernon from the task library NoonTide. The example passes the argument –aux to the task.
wrunjob ps_vernon -l NoonTide -a aux##############################################################Task Name: psTask Endpoint: vernon (ManagedNode)Return Code: 0------Standard Output------USER PID %CPU %MEM SZ RSS TT STAT START TIME COMMANDroot 2245 54.5 6.2 360 2368 ? S 13:10 0:02 task_endpointroot 2246 19.7 1.3 228 488 ? R 13:10 0:00 /tmp/ taskAAAa02245 auxnobody 2244 14.6 5.2 176 1992 ? S 13:10 0:01 man_node_skel1nobody 2239 12.2 7.3 568 2800 ? S 13:10 0:02 repository_ skel1root 134 8.4 2.9 1508 1100 ? S Apr 19 0:41 oserv -p -k/usr/Tivo
nobody 2237 3.5 5.7 184 2188 ? S 13:10 0:01 library_ skel1root 2236 1.1 5.5 120 2108 p0 S 13:09 0:01 wrunjob ps_vernon -l Nooroot 172 0.0 1.8 136 684 ? S Apr 19 0:02 ./usrlnkd------Standard Error Output------###############################################################
SEE ALSOwcrtjob, wcrttask, wgetjob
wrunquery
Tivoli Management Framework Reference Manual 1–417
Com
mands
wrunqueryRuns a query and returns the results to either standard output or a file.
SYNOPSISwrunquery [–n] [[–h host_name] –f file_name] [–d delimiter] query_name
DESCRIPTIONThe wrunquery command runs a query and enables you to either display the results or save them to a file. By default, the wrunquery command will return the output to standard output. To get a list of object IDs and object labels to use for a subscription list, use the wruninvquery command.
Authorization
Query_execute, RIM_view, admin, senior, or super
Arguments
–n Omits the headers from the output.
–h host_name Specifies the name of the managed node on which to store the query results. If you do not specify a managed node, the file will be saved on the local machine.
–f file_name Specifies the path and name of the file in which to store the query results.
–d delimiter Specifies the delimiter that will separate the entries in the output file. The default delimiter is a comma.
query_name Specifies the name of the query to run.
EXAMPLESThe following command runs the Operating-systems query and sends the output to a file named query.txt on a managed node named amon-sul. The output file will contain headers, and the entries are separated by semicolons.wrunquery -h amon-sul -f query.txt -d ";" Operating-systems
wrunquery
1–418 Version 3.7
The file query.txt contains the following:Query Name Operating-systemsNumber of rows: 9BOOTED_OS_VERSION_TYPE BOOTED_OS_NAME PROCESSOR_SPEED3.2;AIX;UNKNOWN3.2;AIX;UNKNOWN3.2;AIX;UNKNOWN4.1;AIX;UNKNOWN4.1;AIX;UNKNOWN3.10;Windows 25;486 DX3.10;Windows 25;486 DX3.10;Windows 33;486 DX3.10;Windows 133;Intel Pentium
SEE ALSOwcrtqlib, wcrtquery, wgetquery, wruninvquery, wsetquery
wruntask
Tivoli Management Framework Reference Manual 1–419
Com
mands
wruntask Runs a task in a task library.
SYNOPSISwruntask –t task_name –l library_name {–h node… | –p profile_mgr…} [–a argument] [–e name=value] [–iE] [–T transtype] [–M mode [–s interval –n number]] [-r] [–m timeout] [–o output_format]
DESCRIPTIONThe wruntask command runs a task in a task library. The task must have been previously created with wcrttask.
Authorization
You must have the role specified when the task was created. You can use the wgettask command to find the required role.
Arguments
–t task_name Specifies the name of the task to be run.
–l library_name Specifies the task library containing the task to be run.
–h node… Specifies the nodes on which to run the task. You must specify at least one node or at least one profile manager (with the –p argument). The –h argument must be repeated for each node specified (for example, –h vernon –h everest –h fuji).
–p profile_mgr… Specifies the profile managers on which the task will run. You must specify at least one profile manager or at least one node (with the –h argument). The –p argument must be repeated for each profile manager specified (for example, –p pm1 –p pm2 –p pm3).
wruntask
1–420 Version 3.7
–a argument Specifies the argument to be passed to the task. If the argument to be passed includes an option flag and an argument, enclose both in quotation marks (for example, –a “o argument”). The –a argument must be repeated for each argument specified (for example, –a “–h node” –a “–p profile_mgr”).
–e name=value Sets an environment variable for the task. The –e argument must be repeated for each environment variable specified (for example, –e DISPLAY=bald:0.0 –e COLOR=red).
–E Passes to the task all environment variables set in your current shell.
–i Reads standard input and passes it to the task as its standard input.
–T transtype Specifies a transaction type. See “Tivoli Transactions” on page 1-6 for additional information on transaction types. This argument can be one of the following:
top Top-level transaction. This is the default if the –T argument is not specified.
sub Subtransaction.
revoke Revocable transaction.
none No transaction.
–m timeout The amount of time, in seconds, the task library will wait for results to be returned from the task. This argument does not affect the execution of the task. If you do not use the –m argument, the default timeout is 60 seconds.
–M mode Specifies the mode in which the task will be run. Valid options are the following:
parallel Runs the task on all specified managed nodes and any subscribers simultaneously. This is the default if you do not specify the –M argument.
wruntask
Tivoli Management Framework Reference Manual 1–421
Com
mands
serial Runs the task on one managed node at a time.
staged Runs the task on a set number of managed nodes at specified intervals.
–s interval Specifies the number of seconds between when the task runs on one group of managed nodes and when it runs on the next group. You must specify a value for this argument if you selected staged mode.
–n number Specifies the number of managed nodes on which to run the task in each stage. You must supply a value for this argument if you selected staged mode.
–r Returns an error code of 1 if at least one endpoint fails to execute its job properly.
–o output_format Defines the format of the task output. Task execution output format is specified with an octal number from 0 to 17. The format is constructed by adding the value of the desired output. For example, to print the task’s return code to standard output, enter –o 05. To output to a file, use the standard redirection syntax. Output values are as follows:
01 Prints a descriptive header for each record
02 Prints the task’s return code
04 Prints the standard output
08 Prints the standard error output
wruntask
1–422 Version 3.7
EXAMPLES
1. The following example runs task date_task on hosts bald and fuji. The task is contained in task library my_tasks.
wruntask -t date_task -l my_tasks -h bald -h fuji#####################################################Task Name: date_taskManaged Node: baldReturn Code: 0-------Standard Output-------Mon Nov 21 10:49:34 CST 1998-------Standard Error Output-------#####################################################Task Name: date_taskManaged Node: fujiReturn Code: 0-------Standard Output-------Mon Nov 21 10:49:45 CST 1998-------Standard Error Output-------#####################################################
2. The following example runs task date_task2 on host bald. The task is contained in task library my_tasks. The output of this task is standard output.
wruntask -t date_task2 -l my_tasks -h bald -o 04#####################################################Mon Nov 21 10:50:47 CST 1998#####################################################
3. The following example runs the task ps on managed node vernon. The task resides in the task library NoonTide. The example passes the option –aux to the task.
wruntask -t ps -l NoonTide -h vernon -a aux############################################################Task Name: psTask Endpoint: vernon (ManagedNode)Return Code: 0------Standard Output------USER PID %CPU %MEM SZ RSS TT STAT START TIME COMMANDroot 2245 54.5 6.2 360 2368 ? S 13:10 0:02 task_endpointroot 2246 19.7 1.3 228 488 ? R 13:10 0:00 /tmp/ taskAAAa02245 auxnobody 2244 14.6 5.2 176 1992 ? S 13:10 0:01 man_node_ skel1nobody 2239 12.2 7.3 568 2800 ? S 13:10 0:02 repository_ skel1root 134 8.4 2.9 1508 1100 ? S Apr 19 0:41 oserv -p 94 \
wruntask
Tivoli Management Framework Reference Manual 1–423
Com
mands
-k /usr/Tivonobody 2237 3.5 5.7 184 2188 ? S 13:10 0:01 library_skel1root 2236 1.1 5.5 120 2108 p0 S 13:09 0:01 wrunjob ps_ vernon -l Nooroot 172 0.0 1.8 136 684 ? S Apr 19 0:02 ./usrlnkd------Standard Error Output------###############################################################
SEE ALSOwcrttask, wcrtjob, wgettask
wschedjob
1–424 Version 3.7
wschedjob Schedules a job that exists in a task library.
SYNOPSISwschedjob –n name –L library_name –t “mm/dd/yyyy hh:mm”[–c ‘time_period’] [–C daytime | nighttime | weekday | weekend from to][–D] [–d desktop] [–f file –h host] [–g group][–l label] [–m email] [–o] [–r ‘time_period’ | ‘iterations’] [–R ‘time_period’ | ‘iterations’] [–s description]
DESCRIPTIONThe wschedjob command allows administrators to schedule a job using the command line. Only jobs that exist in a task library can be scheduled from the command line. Administrators must also have the proper authorization to execute the job. This is validated when the job is scheduled. If the administrator does not have the proper authorization at the time the job is run, it will fail.
Authorization
admin, senior, super
Arguments
–c ‘time_period’ Specifies when a job will be canceled if it did not start as scheduled. You must specify a number (amount of time) and a unit of time. The unit of time must be minute, hour, or day. For example, if you specify 3 hour, the job will be canceled three hours after its originally scheduled start time.
wschedjob
Tivoli Management Framework Reference Manual 1–425
Com
mands
–C daytime | nighttime | weekday | weekend from to Specifies the conditions or restrictions under which the job will run. The from option can be either a starting day or a starting time. The to option can be either an ending day or an ending time. Times must be entered using a 24-hour clock (for example, 9:00 for 9 a.m. or 14:00 for 2 p.m. Days must be entered as numeric values where Sunday is 0 and Saturday is 6. Valid options are as follows:
‘daytime from to’ Specifies the job will run only during the day between the hours of from and to.
‘nighttime from to’ Specifies the job will run only during the night between the hours of from and to.
‘weekday from to’ Specifies the job will run only during the week on and between the days indicated by from and to.
‘weekend from to’ Specifies the job will run only during the week on and between the days indicated by from and to.
–D Disables the job. The job remains in the scheduler but will not be run until it is enabled.
–d desktop Specifies which desktop will display the Status dialog when any action is performed on the job. Multiple desktops can be specified.
–f file Specifies the file to which the job status will be written when any action is performed on the job. If a file is specified, –h must be used to specify a host.
wschedjob
1–426 Version 3.7
–g group Specifies the notice group to which the job status will be sent when any action is performed on the job. Multiple notice groups can be specified.
–h host Specifies the host on which the job status file is to be written. Must be used with the –f argument.
–L library_name Specifies the name of the task library where the job resides. (Required)
–l label Specifies the name specific to this instance of the job.
–m email Specifies the e-mail address to which the job status will be sent when any action is performed on the job. Multiple e-mail addresses can be specified.
–n name Specifies the name of the job with the task library that will be scheduled. (Required)
–o Specifies that the time indicated with the –t argument is in the past. Overrides warning message.
–r ‘time_period’ | ‘iterations’ Specifies the repeat information. If the iterations option is specified, the job repeats for a finite number of times.
‘time_period’ Specifies how often a job will be retried. You must specify a number (amount of time) and a unit of time. The unit of time must be minute, hour, day, week, month, or year. For example, if you specify ’3 hour’, the job will be repeated every three hours.
wschedjob
Tivoli Management Framework Reference Manual 1–427
Com
mands
‘iterations’ Specifies how many times a job will be repeated. You must specify an amount of time, a unit of time, and a number of times. The unit of time must be minute, hour, day, week, month, or year. For example, if you specify ’3 hour 6’, the job will be repeated every three hours until it has been repeated six times.
–R ‘time_period’ | ‘iterations’ Specifies the retry information. If the iterations option is specified, the job retries for a finite number of times.
‘time_period’ Specifies how often a job will be repeated. You must specify a number (amount of time) and a unit of time. The unit of time must be minute, hour, or day. For example, if you specify ’3 hour’, the job will be retried every three hours.
‘iterations’ Specifies how many times a job will be retried. You must specify an amount of time, a unit of time, and a number of times. The unit of time must be minute, hour, or day. For example, if you specify ’3 hour 6’, the job will be retried every three hours until it has been tried six times.
–s description Describes of the job. Multiword descriptions require quotation marks.
–t “mm/dd/yyyy hh:mm” Specifies the time the job is scheduled to initially execute. (Required)
wschedjob
1–428 Version 3.7
EXAMPLES
1. The following example schedules the job SendWishList from the task library, Holiday. The job will execute at 6:00 a.m. on December 24, 1998. When any action is performed on the job, a job status message will be sent to [email protected].
wschedjob -t "12/24/1998 6:00" -m [email protected] -L \Holiday -n SendWishList
2. The following example schedules the job SendWishList from the task library, Holiday. The job will execute at 6:00 a.m. on December 24, 1998. In this example, when an action is performed on the job, a job status message will be sent to [email protected], [email protected], and [email protected]. The job will repeat every five minutes. If the job fails, it will retry once, one minute after failure.
wschedjob -t "12/24/1998 6:00" -m [email protected] \-L Holiday -n SendWishList -r ’5 minute’ \-m [email protected] -m [email protected] -R ’1 minute 1’
3. The following example schedules the job nice_list from the task library, MakeToys. The job will run Monday through Friday at 10 p.m.
wshedjob -t "3/4/1996 22:00" -L MakeToys -n nice_list \-r ’1 day’ -C ’weekday 1 5’
SEE ALSOwdelsched, wenblsched, wgetsched, wedsched
wserver
Tivoli Management Framework Reference Manual 1–429
Com
mands
wserver Installs the Tivoli Management Region (TMR) server on UNIX machines.
SYNOPSISwserver –c cdrom_path [–a server_name] [–d] [–P] [–p path_prefix[!]] [install_variable=value…]
DESCRIPTIONThe wserver command installs the initial TMR server for a TMR. Two modes of installation are supported: an X11-based installation and a command-line only installation. To use the X11 version of wserver, make sure that your DISPLAY environment variable is set and the environment variable DOGUI is not set. For the command-line only installation, set the environment variable DOGUI to no. By default, the X11 version of installation is chosen. To run wserver in either case, change directory to the install_dir directory; that is, the directory where you ran WPREINST.SH or the directory where you un-tarred FILE0.TAR. Alternatively, you could set the environment variable BINDIR to your install_dir directory.
Authorization
Root access on the system being installed.
Arguments
–c cdrom_path Specifies the path to the CD-ROM image.
–a server_name Specifies the name of the TMR server. You can specify either the local host name or a remote host name. The default is the local host name. On some systems with host names longer than eight characters, the hostname command returns unknown. This argument lets you fix that behavior.
wserver
1–430 Version 3.7
Note: If you are installing on the local host and specifying a fully qualified host name, the appropriate remote access must be enabled by updating the local /.rhosts file.
–p path_prefix[!] Attaches path_prefix to the beginning of the default installation paths. If the optional ‘!’ is present, path_prefix is prepended to only the last component of the default installation paths. For example, the default installation path for Tivoli binaries is /usr/local/Tivoli/bin. If you specify –p /Tivoli, the installation path would be /Tivoli/usr/local/Tivoli/bin. If you specify –p /Tivoli!, the path would be /Tivoli/bin.
–d Sets the installation variable (install_variable) to its default value. This flag is used for only the command line version of wserver.
–P Specifies the use of a global root password instead of trusted host access. This argument is used only when installing on remote hosts.
install_variable=value… Specifies a number of variables that control the installation, which can be set or defaulted on the command line. If you are using the X11-based method of installation, you can also change these values in the installation dialog. Of course, when installing from the command line, the only way to set the values is to pass them on the command line. The installation variables specify required information or override default information.
wserver
Tivoli Management Framework Reference Manual 1–431
Com
mands
Several of the installation variables specify the directories where the TMR server will be installed. If a directory already contains files from a previous installation, wserver will not recopy the files. You can force any of these directories to be reinstalled by entering a ‘!’ character after the specified directory. The following are the installation variables related to the installation directories:
BIN=binaries_dir Overrides the default installation path (/usr/local/Tivoli/bin) for the Tivoli Management Framework binaries.
LIB=libraries_dir Overrides the default installation path (/usr/local/Tivoli/lib) for the Tivoli Management Framework libraries.
ALIDB=server_database_dir Overrides the default installation path (/var/spool/Tivoli) for the Tivoli Management Framework server database.
MAN=man_page_dir Overrides the default installation path (/usr/local/Tivoli/man) for the Tivoli Management Framework manual pages.
APPD=X11_app_defaults_dir Overrides the default installation path (/usr/lib/X11/app-defaults) for the X11 application defaults.
CAT=message_catalog_dir Overrides the default installation path (/usr/local/Tivoli/msg_cat) for the Tivoli Management Framework message catalogs.
wserver
1–432 Version 3.7
The following are other useful installation variables:
@EL@=None | Simple DES Defines the encryption level to be used when installing the server. The default level is Simple.
LK=license_key Specifies the license key for the Tivoli product.
RN=region_name Overrides the default policy region name. The default policy name can be changed later.
IP=installation_password Sets the installation password. By default, there is no password. This password is the installation password when you install Tivoli on clients, the default seed when you are using encryption, and the interregion password when you are connecting TMRs using encryption.
AutoStart=0 | 1 Indicates whether the Tivoli daemon should be started at system boot time. By default, the daemon is not started.
SetPort=0 | 1 Indicates whether to configure the remote start capability of the Tivoli daemon. By default, this capability is not configured.
CreatePaths=0 | 1 Indicates whether to create the specified directories if they do not already exist. By default, the directory is not created. It is considered an error if a directory you specified with an installation variable does not exist.
wserver
Tivoli Management Framework Reference Manual 1–433
Com
mands
@ForceBind@=yes | no Forces Tivoli communication connections to bind to a single Internet Protocol (IP) address. This option is used in certain high availability or failover configurations where multiple object dispatchers reside at different IP addresses on a single physical system.
EXAMPLESAll of the following examples show command line installations. The environment variable DOGUI is set to no. The X11 version of installation is similar.
1. The following example installs the TMR server on the local machine. The complete path to the CD-ROM image is /cdrom/cdrom0. The binaries will be installed in /Tivoli/bin. The libraries will be installed in /Tivoli/lib. The Tivoli database will be installed in /Tivoli/database. The man pages will be installed in /Tivoli/man. The X11 app-defaults will be installed in /Tivoli/X11. The message catalogs will be installed in /Tivoli/cat. The server will be installed with the license key 1234567890XYZZY. A default policy region will be created with the name NoonTide-Region. The Tivoli daemon will automatically start at system boot time. The remote start capability of the Tivoli daemon will be configured. The specified directories will be created if they do not exist. The installation password is set to Tivoli4Ever. The default encryption level will be used.
./wserver –c /cdrom/cdrom0 BIN=Tivoli/bin \LIB=Tivoli/lib ALIDB=/Tivoli/database MAN=/Tivoli/man \AAPD=/Tivoli/X11 CAT=/Tivoli/cat \LK=1234567890XYZZY RN=NoonTide-Region AutoStart=1 \SetPort=1 CreatePaths=1 IP=Tivoli4Ever
wserver
1–434 Version 3.7
Note: To reinstall a TMR server, you must force the installation to overwrite the directory containing the Tivoli database (ALIDB=!). You can optionally overwrite any other directories. Use the exclamation mark (!) to force the installation to overwrite directories that already exist. The following command line reinstalls the TMR server installed with the command above, overwriting each directory:
./wserver –c /cdrom/cdrom0 \BIN=! LIB=! ALIDB=! MAN=! APPD=! CAT=! \LK=1234567890XYZZY RN=NoonTide-Region AutoStart=1 \SetPort=1 CreatePaths=1 IP=Tivoli4Ever
2. The following example installs the TMR server on the local machine. The complete path to the CD-ROM image is /cdrom. The binaries will be installed in /Tivoli/bin. The libraries will be installed in /Tivoli/lib. The Tivoli database will be installed in /Tivoli/database. The man pages will be installed in /Tivoli/man. The server will be installed with the license key 1234567890. A default policy region will be created with the name NoonTide.
wserver -c /cdrom -d -p /Tivoli! ALIDB=/database \LK=1234567890 RN=NoonTide
3. The following example installs the TMR server on the local machine. The complete path to the CD-ROM image is /cdrom. The binaries will be installed in /Tivoli/bin. The libraries will be installed in /Tivoli/lib. The Tivoli database will be installed in /Tivoli/database. The man pages will be installed in /Tivoli/man. The server will be installed with the license key 1234567890. A default policy region will be created with the name NoonTide.
wserver -c /cdrom BIN=/Tivoli/bin LIB=/Tivoli/lib \ALIDB=/Tivoli/database MAN=/Tivoli/man LK=1234567890 \RN=NoonTide
4. The following example installs the TMR server on the local machine. The complete path to the CD-ROM image is /cdrom. Everything (binaries, libraries, and so on) will be installed in the default locations under the user-specified directory /Tivoli. The server will be installed with the license key ABCDEFGHIJKLMNO.
wserver -c /cdrom -d LK=ABCDEFGHIJKLMNO
wserver
Tivoli Management Framework Reference Manual 1–435
Com
mands
5. The following example installs the TMR server on the remote machine cook. The complete path to the CD-ROM image is /cdrom, and this path must be reachable from both the local machine and the remote machine (cook). The user will be prompted to enter the root password of the machine cook. Everything (binaries, libraries, and so on) will be installed in the default locations. The server will be installed with the license key ZYXWVUTSRQPONM.
wserver -c /cdrom -P -d -a cook LK=ZYXWVUTSRQPONM
ENVIRONMENT VARIABLES
A number of environment variables have installation implications:
DISPLAY Specifies the X11 display to be used for installation.
DOGUI If set to something other than the value of the $DISPLAY variable, the command line version of wserver will be used.
EtcTivoli Overrides the default location of the /etc/Tivoli directory on the TMR server.
BINDIR If you do not want to run wserver from the install_dir directory (the directory where you ran WPREINST.SH from or the directory that you un-tarred FILE0.TAR into) you can set this variable to your install_dir directory.
o_dispatch Overrides the network port used by the Tivoli object dispatcher. The default port, 94, is registered for use by Tivoli.
SAVE_CFG_FILES The debugging files used during initialization of the TMR server, /tmp/install.cfg.output and /tmp/install/cfg.error, are removed after a successful installation. If you want to keep them, you can set this variable to a nonnull value.
wserver
1–436 Version 3.7
FILES
/tmp/tivoli.sinstall Contains verbose debugging information from the latest installation attempt.
/tmp/install.cfg.error /tmp/install.cfg.output Transient file created during the initialization of the TMR server database. After initialization, if there are no errors, these files are removed.
/etc/Tivoli/setup_env.sh A file that can be dotted from Bourne shell compatible shells after installation that contains useful shell environment variables.
/etc/Tivoli/setup_env.csh A file that can be dotted from csh compatible shells after installation that contains useful shell environment variables.
SEE ALSOwclient, winstall
wsetadmin
Tivoli Management Framework Reference Manual 1–437
Com
mands
wsetadmin Changes information about a Tivoli administrator.
SYNOPSISwsetadmin [–L login] [–l login] [–n notice_group][–N notice_group] [–R group] [–r group,role1:role2…] name
DESCRIPTIONThe wsetadmin command changes the properties of an existing Tivoli administrator. An administrator login can be added or removed, and an administrator’s group roles and notice group subscriptions can be changed.
Authorization
senior or super
Arguments
–L login Removes the specified login.
–l login Adds the specified login.
–N notice_group Removes a subscription from a notice group.
–n notice_group Adds a subscription to a notice group.
–R group Removes all roles for the administrator in the group.
–r group,role1:role2… Changes the administrator’s role in group to the specified role. The following are examples of valid formats for this argument:
@Administration@PolicyRegion:Administration/Regions/PolicyRegion:Administration
name The name of the administrator whose properties to change.
wsetadmin
1–438 Version 3.7
EXAMPLES
1. The following example changes information for administrator Steve Callahan. The administrator’s role in the Accounting policy region will be admin. He will no longer be subscribed to the Tivoli Authorization notice group, and the login callahan@teton will be added.
wsetadmin -r @Accounting,admin -N "Tivoli Authorization" \-l callahan@teton "Steve Callahan"
2. The following example again changes information for administrator Steve Callahan. The example removes his authorization in the Accounting policy region. It adds a subscription to the Tivoli Authorization notice group, and removes the login callahan@teton.
wsetadmin -R @Accounting -n "Tivoli Authorization" \-L callahan@teton "Steve Callahan"
SEE ALSOwcrtadmin, wgetadmin
BUGSYou cannot use wsetadmin to change the user name, the group name, or the label of the Administrator icon. You must make these changes from the desktop.
wsetdfpol
Tivoli Management Framework Reference Manual 1–439
Com
mands
wsetdfpol Sets the default policy object for a class.
SYNOPSISwsetdfpol [–d | –v] class label
DESCRIPTIONThe wsetdfpol command sets the names of the default policy default and policy validation objects for the specified managed class in the current policy region. When a managed class is added to a policy region, it receives the specified default policy objects.
A policy default object generates default attribute values for resources created in a policy region. A policy validation object validates attribute values for a managed class.
Authorization
admin, senior, super
Arguments
–d Sets the default policy default object. This action is the default unless –v is specified.
–v Sets the default policy validation object.
class Specifies the class for which the default policy object is to be set.
label Specifies the label of the desired policy object.
EXAMPLESThe following example makes the policy validation object, Restricted, the default policy validation object for the ProfileManager class. wsetdfpol -v ProfileManager Restricted
SEE ALSOwgetdfpol
wseterr
1–440 Version 3.7
wseterrSets the return code from a batch file for a configuration program. This command should be run from an endpoint. (All supported PC platforms)
SYNOPSISwseterr return_code
DESCRIPTIONThe wseterr command sets the return code for a batch file invoked as a configuration program. Tivoli recommends that you specify this command at the end of all batch files to return the proper code to Tivoli Software Distribution.
Arguments
return_code Specifies the return code to be returned.
wsetjob
Tivoli Management Framework Reference Manual 1–441
Com
mands
wsetjob Sets the properties of a job.
SYNOPSISwsetjob –j job_name –l library_name [–t task_name] [–M mode] [–s interval –n number] [–m timeout] [–o output_format] [–D] [–d mannode_name –f file_name] [–h mannode_name] [–p prof_manager_name]
DESCRIPTIONThe wsetjob command sets the properties of a job using the specified task.
Authorization
admin, senior, super
Arguments
–j job_name The name of the job being created.
–l library_name Specifies the task library containing the task to be included in the job.
–t task_name The name of the task to include in the task library.
–M mode Specifies the mode in which the job will be run. Valid options are the following:
serial Runs the job on all specified managed nodes and any subscribers simultaneously.
parallel Runs the job on one managed node at a time.
staged Runs the job in groups of managed nodes at specified intervals. The required arguments for –M staged are –s interval, –n number, and –m timeout.
wsetjob
1–442 Version 3.7
–s interval Specifies the number of seconds between when the task runs on one group of managed nodes and when it runs on the next group. You must specify a value for this argument if you selected staged mode. The interval must be greater than the timeout value given with the –m argument.
–n number Specifies the number of managed nodes in each group in staged mode. You must specify a value for this argument if you selected staged mode.
–m timeout The number of seconds the task library will wait for results to be returned from the task. If you are using staged mode, the timeout must be smaller than the interval time.
–o output_format Defines the format of the job output. The job output contains a summary of the job on each managed node. Job output format is specified with a number from 0 to 15. The format is constructed from the OR of any of the following values:
01 Prints a descriptive header for each record
02 Prints the job’s return code
04 Prints the standard output
08 Prints the standard error output
–D Displays the job output to the screen.
–d mannode_name Specifies the managed node on which to save the job output.
–f file_name Specifies the file name in which to save the job output.
–h mannode_name Specifies the managed nodes on which to run the job.
–p prof_manager_name Specifies the profile managers on which the job will run.
wsetjob
Tivoli Management Framework Reference Manual 1–443
Com
mands
SEE ALSOwcrttask, wsettask, wrunjob, wdeljob
wsetlang
1–444 Version 3.7
wsetlangSets the locale for Tivoli method execution on a Tivoli Management Region (TMR) server or managed node.
SYNOPSISwsetlang [–o] [–l locale_name]
DESCRIPTIONThe wsetlang command sets the language environment for a TMR server or managed node. The specified locale name can either be a valid operating system locale name or a standard locale name. A locale name is composed of the two-letter ISO 639 language code followed by an optional underscore (_) and two-letter ISO 3166 country code. The standard syntax is as follows:11[_TT]
where ll represents the language code and _TT is the optional country code.
The operating system locale names on UNIX machines can be listed using the following UNIX command: locale -a
On UNIX systems, the specified locale name is mapped to the installed operating system locale name that it most closely matches. If no matching locale name is found, C is used. Windows NT systems simply use the specified locale name. It is not validated.
Standard locale names include the following:
en or C English
fr French
de German
it Italian
ja Japanese
pt_BR Brazilian Portuguese
ko Korean
zh_CN Simplified Chinese
wsetlang
Tivoli Management Framework Reference Manual 1–445
Com
mands
zh_TW Traditional Chinese
Authorization
super or senior
Arguments
–l locale_name Specifies the desired locale. If the –l argument is not specified, the current language environment is used.
–o Sets the language for this TMR server or managed node to the specified value.
EXAMPLES
1. To set the locale to French and update the odadmin environment for methods, enter the following command:
wsetlang –o –l fr
The method environment settings can be viewed using the following command:
odadmin environ get
2. To just view the operating system locale name for French, enter the following command. This does not update the method environment.
wsetlang -l fr
wsetpkey
1–446 Version 3.7
wsetpkeyEncrypts and stores a password in the registry.
SYNOPSISwsetpkey [–a key [–k]] | [–d key]
DESCRIPTIONThe wsetpkey command will encrypt and store a password in the Windows NT registry. The encrypted password is stored under a key you provide.
Arguments
–a Adds or replaces a key and password.
–d Reads the password from standard input without prompting, or from the console without echo.
–k Deletes the key and password.
EXAMPLESThe following example adds the admin_key:wsetpkey –a admin_key
wsetpm
Tivoli Management Framework Reference Manual 1–447
Com
mands
wsetpm Enables or disables a profile manager to operate in dataless mode.
SYNOPSISwsetpm [–d | –D] @ProfileManager:prof_manager_name
DESCRIPTIONThe wsetpm command specifies whether a profile manager runs in dataless mode. The dataless mode enables profile managers to distribute to endpoints that have no client database. Endpoints can subscribe to profile managers running in the dataless mode. A managed node can subscribe to any profile manager regardless of the profile manager’s distribution mode. If a dataless profile manager distributes to a managed node, the managed node’s database is ignored during the distribution.
Authorization
admin, senior, super
Arguments
–d Specifies that prof_manager_name operates in a dataless mode.
–D Specifies that prof_manager_name does not operate in a dataless mode. You must remove all endpoint subscribers before you disable the dataless mode on a profile manager.
@ProfileManager:prof_manager_name Identifies the name of the profile manager.
EXAMPLES
1. The following example sets the profile manager, Admin Server, to operate in dataless mode. Endpoint subscribers will be allowed.
wsetpm -d @ProfileManager:AdminServer
2. The following example sets the profile manager, TopLevel, to not accept endpoint subscribers. Dataless operation is disabled.
wsetpm -D @ProfileManager:TopLevel
wsetpr
1–448 Version 3.7
wsetprAssigns the policy used in a policy region, enables or disables policy validation, and adds or removes a managed resource in a policy region.
SYNOPSISwsetpr [–d default_pol] [–v validation_pol] [–E | –e] resource region
wsetpr [–r] resource region
DESCRIPTIONThe wsetpr command specifies which default or validation policy will be used for the specified resource in the specified policy region. If the –E or –e argument is used, this command enables or disables policy validation for the specified resource in the specified policy region. The wsetpr command also adds or removes a managed resource in a policy region. By default, the command adds the specified resource to the policy region. To remove a managed resource, use the –r argument.
Authorization
policy in addition to senior or super
Arguments
–d default_pol Specifies the label of the default policy to be used for the managed resource.
–v validation_pol Specifies the label of the validation policy to be used for the managed resource.
–E Disables policy validation.
–e Enables policy validation.
–r Removes the specified resource from the policy region.
resource Specifies the managed resource type.
region Specifies the label of the target policy region.
wsetpr
Tivoli Management Framework Reference Manual 1–449
Com
mands
EXAMPLES
1. The following example adds resource TaskLibrary to the Engineering policy region:
wsetpr TaskLibrary @PolicyRegion:Engineering
2. The following example enables policy validation for the TaskLibrary resource in the Engineering policy region. The default policy is BasicTaskLibrary and the validation policy is BasicTaskLibrary.
wsetpr -d BasicTaskLibrary -v BasicTaskLibrary -e \TaskLibrary @Engineering
SEE ALSOwcrtpr, wgetpr, wdelpr
wsetquery
1–450 Version 3.7
wsetqueryEdits the properties of a query.
SYNOPSISwsetquery [–n name] [–d desc] [–r repository] [–v view] [–c column…] [–i | –s | –w where_clause] [–x] query_name
DESCRIPTIONThe wsetquery command enables you to change information about an existing query. You can change the query name, description, repository, view, columns list, and the where clause.
Authorization
Query_edit, admin, senior, or super
Arguments
–n name Changes the name of the query.
–d desc Changes the description of the query.
–r repository Changes the repository from which the query gets information.
–v view Changes the view or table that the query uses to retrieve information from the database.
–c column… Changes the column or columns from which the query will retrieve information. To include more than one column, use multiple –c clauses. The columns in the output will be ordered according to how you enter them here.
–i Reads a new where clause from standard input.
–s Reads a new structured clause from standard input. The clause should be in the following format:
[AND | OR] [NOT] Column_Name {= | != | < | <= | > | >= | LIKE | IN} Column_Value
–w where_clause Reads a new where clause from the command line.
wsetquery
Tivoli Management Framework Reference Manual 1–451
Com
mands
query_name Specifies the query to be changed.
–x Specifies that the output of the query will not contain duplicate rows.
EXAMPLES
1. The following example changes the where clause of the DOS-machines query to check the operating system version as well as the operating system name. It reads the new where clause from the command line.
wsetquery -w "BOOTED_OS_NAME = ’DOS’ AND \BOOTED_OS_VERSION LIKE ’6.%’" DOS-machines
2. The following example changes the name of the DOS-machines query to AIX-machines, changes the description of the query, and reads a new where clause from standard input.
wsetquery -i -n AIX-machines -d "Find all the AIX \machines" DOS-machines <<EOF
(BOOTED_OS_NAME = ’AIX’)
EOF
SEE ALSOwcrtqlib, wcrtquery, wgetquery, wruninvquery, wrunquery
wsetrim
1–452 Version 3.7
wsetrimEdits the properties of an RDBMS Interface Module (RIM) object.
SYNOPSISwsetrim [–n name] [–d database] [–u user] [–H db_home][–s server_id] [–I instance_home] rim_name
DESCRIPTIONThe wsetrim command changes the database information for a given RIM object. You can change the database ID, database user, database home, database server ID, and instance home. To change the managed node or vendor for a RIM object, you must delete the object using the wdel command and re-create it using the wcrtrim command. To change the label, you can either delete and re-create the RIM object, or you can use the _set_label method if Tivoli Application Development Environment is installed.
Authorization
senior or super in Tivoli Management Region (TMR)
Arguments
–n name Changes the name of the RIM object to name.
–d database Changes the name of the database to which the RIM object will connect. If you are using DB2, specify any name other than “inventory.”
–u user Changes the name of the database user that the RIM object will use. If you are using DB2, specify a valid UNIX user.
–H db_home Changes the path to the database home directory. This argument changes the environment variables ORACLE_HOME, SYBASE, and DB2DIR for Oracle, Sybase, and DB2, respectively.
wsetrim
Tivoli Management Framework Reference Manual 1–453
Com
mands
–s server_id Changes the server ID for the database. This argument changes the environment variables TWO_TASK, DSQUERY, and DB2COMM for Oracle, Sybase, and DB2, respectively. For Microsoft SQL Server, this is the name of the relational database management system (RDBMS) server machine.
–I instance_home For DB2 only, changes the name and path of the DB2 instance for the specified RIM object.
rim_name Specifies the label of the RIM object to be modified.
EXAMPLESThe following example changes the database ID to inventory, the database user to tivoli2, the database home directory to /ORACLE, and the database server ID to invdb2.world for the inventory RIM object. wsetrim -d inventory -u tivoli2 -H /ORACLE \-s invdb2.world inventory
To verify the changes, use the wgetrim command:wgetrim inventory
The output is as follows. Note that the output for the Instance Home field is blank; this field applies only to DB2.RIM Host: amon-sulRDBMS User: tivoli2RDBMS Vendor: OracleDatabase ID: inventoryDatabase Home: /ORACLEServer ID: invdb2.worldInstance Home:
SEE ALSOwcrtrim, wgetrim, wsetrimpw
wsetrimpw
1–454 Version 3.7
wsetrimpwSets the database password for an RDBMS Interface Module (RIM) object.
SYNOPSISwsetrimpw rim_name [old_pw new_pw]
DESCRIPTIONThe wsetrimpw command sets the database password on a RIM object. The command prompts you for a password unless you specify the old_pw and new_pw options.
Authorization
senior or super in Tivoli Management Region (TMR)
Arguments
rim_name Specifies the label of the RIM object.
old_pw Specifies the current password.
new_pw Specifies the new password.
EXAMPLESTo change the password from funEguy to Dlite for the inventory RIM object, enter:wsetrimpw inventory funEguy Dlite
SEE ALSOwcrtrim, wgetrim, wsetrim
wsettap
Tivoli Management Framework Reference Manual 1–455
Com
mands
wsettap Sets the properties of the Tivoli Authentication Package (TAP) on a Windows NT client.
SYNOPSISwsettap [–a] [–d] [–r [domain_name\user_name|user_name]] [–k]
DESCRIPTIONThe wsettap command sets the properties of Tivoli Authentication Package, TivoliAP.dll. TAP enables Tivoli to access remote file systems in the context of a user. (See the Tivoli Management Framework Planning for Deployment Guide for additional information about accessing remote file systems.) wsettap also enables Windows NT to run setuid methods, that is, to run a method in the context of a user associated with the method.
The Tivoli Remote Access Account (TRAA) specifies a user account. Tivoli uses this account to access remote file systems.
Using the wsettap command with no arguments prints version information from the currently running TivoliAP.dll.
When activating TAP for the first time, which is usually immediately following Tivoli Management Region (TMR) server installation, you must reboot the machine for the TAP changes to take effect.
Authorization
Member of the Administrators group. Tivoli admin authorization is required to run wsettap with no arguments.
Arguments
–a Sets the TAP internal key and registers the TivoliAP.dll with the local security authority (LSA). The new internal key becomes effective immediately. The TivoliAP.dll file is loaded by the LSA when the machine is rebooted.
wsettap
1–456 Version 3.7
–d Removes the TAP internal key and unregisters the TivoliAP.dll with the LSA. The TivoliAP.dll file is released by the LSA (so it can be deleted if Tivoli is uninstalled) when the machine is rebooted.
–r [domain_name\user_name | user_name] Sets the TRAA to user_name. Tivoli accesses remote file systems using this user account. user_name can be prefixed with the domain name, separated by either a forward slash (/) or a backslash (\). If the domain is specified, it must be the domain in which the machine running TAP belongs or a domain trusted by that domain. If no domain is specified, Windows NT looks for the given user in the local domain or trusted domains. wsettap –r "" disables Tivoli access to remote file systems. To see changes take effect immediately, restart the object dispatcher.
–k Specifies that wsettap should read the password for user_name from standard input. If you do not specify –k, wsettap will prompt you for the password.
EXAMPLESThe following example sets the TRAA to a user account called userTME. wsettap will read the password for userTME from the file pswd.file.wsettap -r userTME -k < pswd_file
wsettask
Tivoli Management Framework Reference Manual 1–457
Com
mands
wsettask Sets the properties of a task.
SYNOPSISwsettask –t task_name –l lib_name [–g group_name] [–u user_name] –r role [–c comments] {–i interp_type mannode_name filename}…
DESCRIPTIONThe wsettask command sets the properties of a task in the specified task library.
Authorization
admin, senior, super
Arguments
–t task_name Specifies the name of the task being updated.
–l lib_name Specifies the task library in which the task resides.
–g group_name (UNIX only) Specifies the name of the group under which the task will run.
–u user_name Specifies the name of the user under which the task will run.
–r role Specifies the authorization roles required to run the task. Multiple roles can be specified in a colon-separated list, for example admin:senior:super.
–c comments Adds any explanatory comments that help identify the task and its purpose.
–i Defines the information required to execute the new task on a managed node. You must supply the following values with the –i argument:
interp_type Specifies the interpreter type of the platform on which the task is to be run.
wsettask
1–458 Version 3.7
mannode_name Specifies the managed node containing the executable file for the specified platform.
filename Specifies the name of the executable file to be run on the specified platform.
SEE ALSOwcrttask, wgettask, wdeltask
wsetval
Tivoli Management Framework Reference Manual 1–459
Com
mands
wsetvalSets a registry key value. This command should be run from an endpoint. (Windows 95, Windows 98, and Windows NT only)
SYNOPSISwsetval [–b] [–d] [–h registry_hive] –k {key | @filename} –n value_name –v {“value_string” | @filename}
DESCRIPTIONThe wsetval command replaces a key value in the registry. If the key or value does not exist, it is created.
Authorization
administrator
Arguments
–b Creates the value as binary. Binary values must be read from a file specified with the –v argument.
–d Deletes a value name specified by the –n argument or a key name specified by the –k argument. The –d argument takes no parameters. If the –n argument is present, the value name specified by the –n argument will be deleted. If the –n argument is not present, then the key (and all its subkeys) specified by the –k argument will be deleted.
–h registry_hive Specifies the registry hive to update. Valid values are as follows:
HKEY_LOCAL_MACHINE (default)HKEY_CURRENT_USERHKEY_CLASSES_ROOTHKEY_USERSHKEY_CURRENT_CONFIG (Windows NT 4.0)HKEY_DYN_DATA (Windows NT 4.0)
wsetval
1–460 Version 3.7
–k key | @filename Specifies the key in which the value is inserted. If the first character of the key is @, the key is read from filename.
–n value_name Specifies the name of the value. The –n argument is optional if –d is present.
–v “value_string” | @filename Specifies the value or file that contains the value. The –v argument is ignored if –d is present.
EXAMPLESTo add the NOTEPAD subkey under the existing SOFTWARE key, and assign the NOTEPADVAR key value name in the HKEY_LOCAL_MACHINE hive, enter the following command:wsetval -h HKEY_LOCAL_MACHINE -k SOFTWARE\NOTEPAD \-n NOTEPADVAR -v C:\TEMP\NTPADVAR.FIL
wsndnotif
Tivoli Management Framework Reference Manual 1–461
Com
mands
wsndnotif Translates standard input into a message structure and sends it to the notification server.
SYNOPSISwsndnotif [–et] ngroup priority
DESCRIPTIONThe wsndnotif command is a command line program that translates standard input into a message structure and sends it to the notification server. The –e and –t arguments enable shell scripts to send messages in a language-neutral format. If these arguments are not specified, this command treats standard input as a single ASCII buffer and the message is not translated into a language-neutral format. This command sends the message to the specified notice group using the specified priority.
Authorization
user, senior, super
Arguments
–e Specifies that standard input is the ASCII representation of an exception, such as an exception generated from an Interface Definition Language (IDL) call.
–t Specifies that standard input should be translated as a tmf_msg_t in the ASCII format used by the Extended Interface Definition Language (EIDL) shell method type. For more information about the ASCII format used by the EIDL shell method type, see the TME 10 ADE Framework Services Manual.
ngroup Specifies the notice group to send the translated standard input to.
priority Specifies the priority to use to send the translated standard input to the specified notice group. Valid priorities are Critical, Error, Warning, Notice, and Debug.
wsndnotif
1–462 Version 3.7
EXAMPLES
1. The following example sends a notice to the Tivoli Administration notice group. The priority is Notice.
wsndnotif "Tivoli Administration" NoticeThis notice is to inform all admins that I’m going tochange the name of managed node homer to marge this weekend.
Paul^D
2. The following example uses the –e argument in a shell script. If an IDL call returns a nonzero exit status, the ASCII output is an exception. The ASCII data is logged to the Tivoli Administration notice group as an error.
out=‘idlcall $OID method‘if [ $? -ne 0 ]thenwsndnotif -e "Tivoli Administration" Error <<EOF$outEOFfi
3. The following example uses the –t argument in a shell script. This example sends message 49 from the task_msg message catalog to the Tivoli Administration notice group. Strings Amar, [email protected], and AmarLib will be inserted into the message. If message 49 cannot be found, the default message will be sent. The default message is “A new task %1$s, was created by %2$s in the %3$s task library.”
echo ’{ { 1 { "task_msg" "A new task, %1$s, was created by \%2$s \in the %3$s task library." 49 { { \TMF_Types::_sequence_string_StringList } \{ 3 "Amar" "[email protected]" \"AmarLib" } } } } }’ | \
wsndnotif -t "Tivoli Administration" Critical
SEE ALSOwlsnotif, wexpnotif, wtailnotif
wstarthttpd
Tivoli Management Framework Reference Manual 1–463
Com
mands
wstarthttpdStarts the Tivoli Hypertext Transfer Protocol (HTTP) daemon.
SYNOPSISwstarthttpd [host_name]
DESCRIPTIONThe wstarthttpd command starts the Tivoli HTTP daemon on the host that is specified by host_name. If host_name is not specified, the HTTP daemon on the local managed node is started.
Authorization
admin, senior, super
Arguments
host_name Specifies the name of the managed node on which to start the HTTP daemon.
EXAMPLESThe following example starts the HTTP daemon on the managed node ccorley:wstarthttpd ccorley
SEE ALSOwstophttpd
wstartsched
1–464 Version 3.7
wstartsched Starts the Tivoli scheduler.
SYNOPSISwstartsched
DESCRIPTIONThe wstartsched command starts the Tivoli scheduler. The process it starts is TMF_sched.
Authorization
senior
SEE ALSOwschedjob, wedsched, wgetsched, wdelsched, wenblsched
wstophttpd
Tivoli Management Framework Reference Manual 1–465
Com
mands
wstophttpdStops the Tivoli Hypertext Transfer Protocol (HTTP) daemon.
SYNOPSISwstophttpd [host_name]
DESCRIPTIONThe wstophttpd command stops the Tivoli HTTP daemon on the host that is specified by host_name. If host_name is not specified, the HTTP daemon on the local managed node is stopped.
Authorization
admin, senior, super
Arguments
host_name Specifies the name of the managed node on which to stop the HTTP daemon.
EXAMPLESThe following example stops the HTTP daemon on the managed node ccorley:wstophttpd ccorley
SEE ALSOwstarthttpd
wsub
1–466 Version 3.7
wsub Subscribes Tivoli resources to a profile manager.
SYNOPSISwsub [–r] name subscriber…
DESCRIPTIONThe wsub command subscribes the Tivoli resources specified in subscriber to the profile manager specified in name.
Authorization
admin, senior, or super in the policy region where the resource is being subscribed
Arguments
–r Specifies that the wsub command returns an error code (1) if any of the subscribers were unreachable. A failure code is always returned if the specified subscriber does not exist.
name The name of the profile manager to which to subscribe the resources. Valid formats for the name option include:
■ @prof_manager_name
■ @ProfileManager:prof_manager_name
■ /Regions/PolicyRegionName/prof_manager_name
wsub
Tivoli Management Framework Reference Manual 1–467
Com
mands
subscriber The names of the Tivoli resources to add to the specified profile manager’s subscription list. This option can be specified multiple times. The following are examples of valid formats for the subscriber option. If you are subscribing a resource other than a managed node, modify these examples to reflect your resource type.
■ @ManagedNode:node_name
■ /Regions/PolicyRegionName/node_name
EXAMPLESThe following example subscribes the managed nodes pinatubo, newcastle, and the profile manager Apps_Dev to the Development profile manager: wsub @Development @ManagedNode:pinatubo \@ManagedNode:newcastle @ProfileManager:Apps_Dev
SEE ALSOwcrtprf, wcrtprfmgr, wgetsub, wlssub, wpopulate, wgetprf, wdistrib, wunsub, wvalidate
wsupport
1–468 Version 3.7
wsupport Collects problem information from users to send to a customer support representative. (UNIX only)
SYNOPSISwsupport –s
DESCRIPTIONThe wsupport command prompts you for essential information needed by a support representative to investigate technical problems.
After the information is entered, you are prompted whether the information will be e-mailed to the support representative or saved to a text file. If you specify e-mail, you must enter the e-mail address to which to send the information. The provided information is mailed in a format that can be parsed, one item per line. If you choose to save the information to a text file, the information is presented in an ordered format that can be faxed to a support representative. You can edit the information before faxing it. You can also e-mail the file at a later time.
If you are going to e-mail the file to a support representative later, it is recommended that you choose the e-mail option when prompted, and then specify No on the final confirmation.
You are prompted for the following customer information:
Name Name of the person submitting the support request.
Company Name Name of the company.
E-mail Address The submitter’s e-mail address if e-mail is available.
Telephone Number The submitter’s telephone number. A telephone number is required if an e-mail address is not provided.
Fax Number The submitter’s fax number.
TMR Number The number of the licensed Tivoli Management Region (TMR).
wsupport
Tivoli Management Framework Reference Manual 1–469
Com
mands
Support E-mail Address The e-mail address of the customer’s Tivoli support provider.
You are prompted for the following system information:
Call ID number The call tracking number of an existing problem logged by your support provider.
System Type The system on which the problem occurred, such as Solaris, HP, or IBM.
Operating System Release The release level of the operating system on which the problem occurred, such as 4.1.3.
Tivoli Product The name of the Tivoli product (such as, Tivoli User Administration, Tivoli Remote Control or Tivoli Inventory) in which the problem occurred. wsupport displays a list of Tivoli products from which to choose.
Tivoli Release The release number of the Tivoli product, such as 3.1 or 3.6.
You are prompted for the following problem information:
Where the problem occurred Whether the problem occurred on the TMR server or the Tivoli client.
Name of server or client Name of the system on which the problem occurred.
Severity of the problem Severity level of the problem. Valid options are as follows:
Critical Customer cannot conduct business, product is inoperative, loss of operations, continuous failures or interruptions, data corruption
wsupport
1–470 Version 3.7
Major Systems or application interrupted but recovered, high risk of reoccurrence, urgent, intermittent failures, significant performance degradation
Minor Problem encountered, irritant, minimal impact to business operations, localized or isolated impact, operational nuisance
No Impact General questions or information needed
Short description Ten to twelve word description of the problem.
Attempted solutions Actions taken that did not solve the problem.
Long description Detailed description of the problem.
The problem information can be saved to .tivoli_rc in the user’s home directory.
Arguments
–s Skips the customer information questions. Prompting begins with the system information questions. Customer information is read from the .tivoli_rc file.
FILES/tmp/wsupport.$UNAME – Generated report file /tmp/sup.$UNAME.uu – Encoded compressed log files
wtailnotif
Tivoli Management Framework Reference Manual 1–471
Com
mands
wtailnotif Connects to the notification server and displays new notices as they are posted.
SYNOPSISwtailnotif [–a admin…] [–g group…] [–l] [–p priority…]
DESCRIPTIONThe wtailnotif command connects to the notification server and displays new notices as they are posted. You can filter the notices by priority, administrator, or group. The –l argument is used to list only notice headers rather than entire notices. If the –l argument is not specified, all notice data is displayed. The –p argument specifies that only notices with the specified priority are to be displayed. Multiple priorities can be specified. The –a argument specifies that only notices posted by the specified administrator are to be displayed. Multiple administrators can be specified. The –g argument specifies that only notices posted to the specified notice group are to be displayed. Multiple groups can be specified. If no arguments are specified with this command, all notices from all notice groups are displayed as they are received.
Authorization
senior, super
Arguments
–a admin… Specifies that only notices posted by the administrator specified by admin are to be displayed. Multiple administrators can be specified.
–g group… Specifies that only notices posted to the notice group specified by group are to be displayed. Multiple notice groups can be specified.
–l Specifies that only notice headers are to be displayed. If this argument is not specified, all notice data is displayed.
wtailnotif
1–472 Version 3.7
–p priority… Specifies that only notices with the priority specified by priority are to be displayed. Multiple priorities can be specified.
EXAMPLESThe following example displays Tivoli Authorization notices as they are posted to the notice group:
The task, date_task, was modified by root@bald from the my_tasks task library. This task is one that will execute as root.wtailnotif -g "Tivoli Authorization"Notice-id: 0Date: Mon Nov 21 14:23:56 1998Notice-Group-Name: Tivoli AuthorizationPriority: Notice
Sent-By-Administrator: root@bald
SEE ALSOwlsnotif, wexpnotif, wsndnotif
wtaskabort
Tivoli Management Framework Reference Manual 1–473
Com
mands
wtaskabort Aborts a task transaction and rolls back any uncommitted changes.
SYNOPSISwtaskabort
DESCRIPTIONThe wtaskabort command is for use within a task shell script. It cannot be used from the command line to cancel a specific task.
When tasks are executed, a transaction model can be specified. Using Tivoli commands, it is possible to perform multiple operations as part of one transaction. Any changes do not become permanent until the task completes and the transaction is committed. If a failure occurs in the task with a non-Tivoli command, the wtaskabort command can be used to abort the transaction and roll back any changes that have not been committed.
EXAMPLESIn the following example, a task was written that registers a special resource in the Tivoli name registry that stores the path to a directory. Next, the directory is created. If the mkdir command fails, the script will execute the abort() function because the shell is running with the –e flag. In the abort() function, wtaskabort is called, which rolls back the change made to the name registry. The special resource does not show up in any subsequent lookups.1 #!/bin/sh2 set -e3 4 #5 # Function to be used to abort a transaction in task shell \
script6 7 #8 abort() {9 return_code=$?10 if [ $return_code -ne 0 ]; then11 wtaskabort12 fi13 }14
wtaskabort
1–474 Version 3.7
15 trap ’abort’ 016 17 #18 # TASK MAIN19 #20 wregister -i -r special_directory /Tivoli/specials \
OBJECT_NIL
21 mkdir /Tivoli/specials
NOTESWhen the wtaskabort command is used, the task will not return any output or the return code. Instead, an error message similar to the following is produced:bald (ManagedNode): The task failed to execute.bald (ManagedNode): System Exception: failure detected by \object adapter:completion status: NOTransaction Error
SEE ALSOwruntask, wrunjob, “Tivoli Transactions” on page 1-6
wtimezone
Tivoli Management Framework Reference Manual 1–475
Com
mands
wtimezone Prints the value of the specified system’s time zone.
SYNOPSISwtimezone host_name
DESCRIPTIONThe wtimezone command prints the time zone of the system specified in the host_name option by printing the number of minutes west of Greenwich mean time (GMT).
Authorization
user, admin, senior, super
Argument
host_name The name of the host time zone to print.
EXAMPLESThe following example shows the time zone of the managed node bald: wtimezone bald360
SEE ALSOwdate, wdiskspace, whostid, wifconfig, winstdir, winterp, wmannode, wmemsize, wping, wuname, wxterm
wtemp
1–476 Version 3.7
wtempDisplays the name of the directory in which Tivoli products create temporary files.
SYNOPSIS
wtemp [–s]
DESCRIPTIONThe wtemp command displays the name of the directory in which Tivoli products create temporary files. It can also confirm that the directory exists and can be written to.
wtemp uses the forward slash (/) in all path names. On Windows NT systems, if you are not using the bash shell, you might need to convert forward slashes to backward slashes (\).
Authorization
No Tivoli authorization role is required.
Arguments
–s Confirms that the directory exists and can be written to.
RETURNSIf the temporary directory does not exist or cannot be written to, it writes a null string to standard output.
EXAMPLES
1. The following example displays the temporary directory on a Solaris system:
wtemp/var/tmp
2. The following example displays the temporary directory on a Windows NT system:
wtemp
c:/Tivoli/db/cdeamqs.db/tmp
wtemp
Tivoli Management Framework Reference Manual 1–477
Com
mands
3. The following example confirms that the temporary directory on an AIX system exists and can be written to:
wtemp -s/tmp
4. The following example shows that the temporary directory either does not exist or cannot be written to:
wtemp -s
wtll
1–478 Version 3.7
wtllImports and exports task library definitions.
SYNOPSISwtll [–r] –p region [–P preprocessor] import_file [preprocessor_options ...]
wtll –i [–p region | –l library_name] [–t task ...] [–P preprocessor] import_file [preprocessor_options ...]
wtll –d [–l library_name] [–P preprocessor] import_file [preprocessor_options ...]
wtll –F export_file –l library_name
DESCRIPTIONThe wtll command is a tool used to import (install) task library definitions and create or modify Tivoli task libraries. The command is also used to export existing task libraries in a form that allows them to be saved offline or transferred to other installations. Task libraries are described with the Task Library Language (TLL) for both import and export purposes.
When importing a new task library into a Tivoli Management Region (TMR), a TLL source file is prepared. All programs or scripts to be used by the tasks are either included directly in the TLL source or are referenced as external files by TLL directives. The wtll command reads and parses the task library definition, validates the various attributes defined in the source, and then either creates or modifies a task library object.
When exporting a task library, wtll creates a tar-format file that contains all materials needed to reconstruct the task library. The collected export files include a TLL description of the tasks along with the code of each task for each platform type supported.
For more information about using the wtll command to create task libraries, see Tivoli Task Library Language Developer’s Guide.
Authorization
admin, senior
wtll
Tivoli Management Framework Reference Manual 1–479
Com
mands
Arguments
–d Runs the wtll command in debug mode. The wtll command checks the syntax of import_file, but does not import the file into the TMR.
–F export_file Creates a tar-format export file of the task library specified by library_name.
–i Inserts a new task or group of tasks into an existing task library. The import file is parsed, and specified tasks are created in the existing task library. The import file can be a complete task library or a list of individual tasks.
Note: It is recommended that you use the wcrttask command to add a task to a task library.
Note: If the import file contains a task library, the task contained must be self contained. The task cannot use the “layout” key word to specify an ArgLayout defined in the task library.
–l library_name Specifies the name of the task library for either exporting or for modifying. The library must be defined in the local TMR.
–P preprocessor Specifies the path to the program to use as a preprocessor on the import file before it is parsed. The cpp command is the mostly commonly used preprocessor.
Any arguments listed on the command line after import_file are assumed to be arguments to be passed to the preprocessor (preprocessor_options).
–p region Specifies the policy region in which to create the new task library. The policy region must exist within the local TMR.
wtll
1–480 Version 3.7
–r Replaces a task library with the library specified in import_file. The existing library and all of its tasks and jobs are deleted, and then the library is re-created with the features specified in the import file. If the library does not already exist, a new one will be created.
–t task Specifies the name of the task to import. The specified task name must be unique within the task library or policy region.
import_file Specifies the file to import. This file can contain a single task to be added to a task library or an entire new task library, which replaces the existing task library.
preprocessor_options Specifies additional preprocessor options. Refer to the documentation for the preprocessor for valid options.
EXAMPLES
1. The following example creates a new task library in the policy region sandia-Region using the TLL source in the file /tmp/tll:
wtll -p sandia-Region /tmp/tll
2. The following example also creates a new task library in the policy region, but it first runs the TLL source through the cpp preprocessor and uses include files from the user’s home directory. The –B and –P arguments are input to cpp. They parse C++ comments in the task library file.
wtll -p sandia-Region -P /usr/lib/cpp /tmp/tll \-B -P
Note: The arguments for the preprocessor can use the same option names as those used for wtll (such as –P). Because of their location in the syntax statement, the command processes the options correctly.
3. This example replaces the task library named my_tasks, which is in the sandia-Region policy region, with the TLL source in /tmp/tll:
wtll -r -p sandia-Region -l my_tasks /tmp/tll
wtll
Tivoli Management Framework Reference Manual 1–481
Com
mands
4. This example exports the task library my_tasks to the file called /tmp/my_tasks.tar:
wtll -F /tmp/my_tasks.tar -l my_tasks
SEE ALSOcpp, tar, wcrttask
wtmrname
1–482 Version 3.7
wtmrnameDisplays or changes the name of the local Tivoli Management Region (TMR).
SYNOPSISwtmrname [–s new_name]
DESCRIPTIONThe wtmrname command displays the name of the local TMR. wtmrname can also be used to change the name, by providing the –s new_name option. In this case, all currently connected TMRs must be connected, so that the name can be verified as unique throughout the installation.
Authorization
The caller must have these roles in the local TMR:
■ super—to set the name
■ super, senior, admin, or user—to display the name
Arguments
–s new_name Changes the TMR name to new_name, after verifying the new name with all connected TMRs.
EXAMPLES
1. The following example displays the local TMR name:
wtmrnamesherman-region
2. The following example sets the local TMR name to patton-region:
wtmrname -s patton-region
SEE ALSOwconnect, wdisconn, wlsconn, wupdate
wtrace
Tivoli Management Framework Reference Manual 1–483
Com
mands
wtrace Provides information to debug methods.
SYNOPSISwtrace [–hjlnuvDEHIJOV] [format_options] –k db_dir
DESCRIPTIONThe wtrace command is used to diagnose problems in custom methods and executable files by examining method input, transactions, and method output.
To use wtrace, you must first turn on tracing within the Tivoli object dispatcher. This causes the creation of a trace log called odtrace.log. This file is created in the database directory of the specified clients. By default, the trace log is 1 MB (512 2-KB-trace records), but this can be changed by restarting the object dispatcher and specifying a new size with the –t argument.
Tracing is persistent across invocations of the object dispatcher. This means that if the object dispatcher restarts, you do not have to reenable tracing. Because wtrace examines the trace log directly, it does not require the object dispatcher to be active, although having an object dispatcher available to run odstat is helpful.
You can use the odadmin utility to enable tracing for single or multiple object dispatchers. The following are some examples:
1. Enable tracing for all object calls on the current object dispatcher:
odadmin trace objcalls
2. Enable tracing for all object calls on all object dispatchers:
odadmin trace objcalls all
3. Enable tracing for error conditions on the current object dispatcher:
odadmin trace errors
4. Enable tracing for object service calls on all object dispatchers:
odadmin trace services all
wtrace
1–484 Version 3.7
5. Enable tracing of object service calls and errors on all object dispatchers:
odadmin trace services allodadmin trace errors all
Output Format
The wtrace command has numerous formatting options that provide varying amounts of displayed data. This section describes two of the common usages of wtrace. See the “Arguments” section for a full list of formatting options.
Four general rules apply to the output format of wtrace.
1. Structure output is enclosed between curly braces ({}).
2. Arrays are enclosed in square brackets ([]).
3. Sequences are structures that have a count field followed by an array of elements.
4. A top-level transaction has the following general format:
{111111:1,111111:1,2:3311
}#4
The most common usage of wtrace is as follows:wtrace -jk /usr/Tivoli/spam.db
The j flag produces a preselected set of information. The output looks like this: loc-ec 676 15:10:36 M-H 1-289 0 NOT_FOUNDObject ID: 333333.1.387#FpPol::FilePackagePolDef#
Method: o_setattrMethod Args: fp_def_src_hostPrincipal: root@albundy (0/0)Path: o_setattrTrans Id:
{333333:1,333333:1,2:405
}, {333333:1,333333:1,2:406
}#3
wtrace
Tivoli Management Framework Reference Manual 1–485
Com
mands
This is a local object call on thread ID 676 run at 15:10:36 local time. The method o_setattr was invoked on object reference 333333.1.387#FpPol::FilePackagePolDef# with the option fp_def_src_host. Error status of NOT_FOUND was returned.
In this verbose form, the transaction ID, the principal invoking the method, the effective user ID and group ID of the method, and the path to the method are also provided.
The following example entry shows an error condition (exception) that was detected: loc-ec 6073 16:28:01 M-hdoq 1-6047 26 e=12Object ID: 333333.1.26
Method: get_allPrincipal: root@ajax (60001/60001)Helper pid: 2419Path: /home/Tivoli/bin/solaris2/TMF/BASESVCS/TNR_prog1Trans Id:
{333333:1,333333:1,7:4042
},{333333:1,333333:1,7:4063
}#3
Input Data: (encoded): "NisDomain" 9999Results: (encoded):“Exception:UserException:SysAdminException::ExException:SysAdminException::ExInvalid:SysAdminException::ExNotFound{"Exception:UserException:SysAdminException::ExException:SysAdminException::ExInvalid:SysAdminException::ExNotFound" "TNR_errors"1 "The resource type %7$s was not found."779578081{
0}"NisDomain"
}
wtrace
1–486 Version 3.7
In this example, root@ajax invoked the get_all method on the name registry (object reference 333333.1.26) with the effective user ID of “nobody” (60001). Input Data shows that the parameter NisDomain was passed to the method. From the error code (e=12) and the output in Results, you can see an exception was detected indicating that a specific resource of type NisDomain was not found.
Arguments
–h Prints header used in the “old” format.
–j Prints the preferred format for normal screens (80 columns).
–l Prints the long form output.
–n Prints additional new lines between transactions.
–u Prints the command’s usage message.
–v Prints in verbose mode (included for backward compatibility).
–D Prints large blocks of input data.
–E Suppresses printing of error records.
–H Suppresses printing of hex dumps.
–I Suppresses printing of input records.
–J Prints the preferred format for wide screens (132 columns).
–O Suppresses printing of output records.
–V Prints the version number of the command.
format_options Specifies additional options that modify formatting of the output. The available formatting options are as follows:
–f Turns off printing of abbreviated numbers (for example, 3.2K instead of 3219).
–e lines Specifies the threshold for line breaks. The default is five.
wtrace
Tivoli Management Framework Reference Manual 1–487
Com
mands
–t tab_size Specifies the tab increment. The default is four characters.
–w width Specifies maximum width of the formatted line. The default is 80.
–W width Specifies minimum width of the formatted line. The default is 70.
–k db_dir Specifies the Tivoli database directory.
BUGSA corrupt trace log can cause wtrace to dump core.
SEE ALSOodadmin
wuname
1–488 Version 3.7
wuname Lists operating system information.
SYNOPSISwuname host_name
DESCRIPTIONThe wuname command lists the operating system for the managed node specified in the host_name option. The command lists the operating system, version number, release number, and the hardware name.
Authorization
user, admin, senior, super
Argument
host_name The host to list the operating system information for.
EXAMPLESThe following example shows the operating system of the managed node bald: wuname baldSunOS bald 5.3 Generic_101318-21 sun4m
SEE ALSOwdate, wdiskspace, whostid, wifconfig, winstdir, winterp, wmannode, wmemsize, wping, wuname, wxterm
wuninst
Tivoli Management Framework Reference Manual 1–489
Com
mands
wuninstUninstalls Tivoli applications from a specified node or from the entire Tivoli Management Region (TMR).
SYNOPSISwuninst
wuninst tag
wuninst –list
wuninst tag –list
wuninst tag node_name [–rmfiles] [options]
DESCRIPTIONThe wuninst command is a wrapper script that invokes product-specific uninstall scripts. This section provides general usage information about the wuninst command. The usage statement for this command differs for each product.
To view the general usage statement, enter the following on the command line: wuninst
To view the usage statement for an individual application, enter the following on the command line: wuninst tag
The tag option is the registered product tag. To view a list of the product tags, enter the following on the command line: wuninst -list
If you include the node_name option, the application specified with tag is removed from the specified node. If node_name is the TMR server, the application is removed from the entire TMR. You will be prompted with a confirmation message before the application is removed from the TMR.
The wuninst command cannot remove Tivoli Management Framework from a node. Use the command to remove Tivoli Management Framework and, therefore, remove the node from a TMR. You should use the wuninst command to remove all application files before running the wunstmn command.
wuninst
1–490 Version 3.7
Authorization
super
Arguments
tag Specifies the product to remove.
node_name Specifies the node to remove the product from. If node_name is the TMR server, the product is removed from the entire TMR.
–rmfiles Indicates that all product files are to be removed from node_name. If this option is not included, the wuninst command removes only the database entries for node_name. If –rmfiles is used on the TMR server, all entries for each node in the TMR is removed.
–list Lists the installed application tags or the node on which a product is installed. If used with the tag option, –list lists the nodes on which the specified product is installed. Without other arguments, –list shows the tags of all installed products.
options Indicates options that might be required by each product. To view the options required to uninstall a particular product, enter wuninst tag on the command line.
EXAMPLES
1. The following example returns the general usage statement of the wuninst wrapper script.
wuninst
2. The following example returns the usage statement to remove Tivoli Software Distribution:
wuninst courier_3.7
3. The following example lists the tags of all products installed in the TMR:
wuninst -list
wuninst
Tivoli Management Framework Reference Manual 1–491
Com
mands
4. The following example lists the nodes on which Tivoli Software Installation Service is installed:
wuninst SIS_3.7 -list
5. The following example removes Tivoli Software Installation Service from node kiwi.
wuninst SIS_3.7 kiwi
6. The following example removes Tivoli Software Installation Service from node pctmp83. Because pctmp83 is the TMR server, Tivoli Software Installation Service is removed from every node in the TMR. The –rmfiles option indicates that all product files are removed as well as database entries.
wuninst SIS_3.7 pctmp83 -rmfiles
SEE ALSOwunstmn
wunstmn
1–492 Version 3.7
wunstmnRemoves Tivoli Management Framework files from a managed node. (Windows NT and UNIX only)
SYNOPSISwunstmn [–A] [–f] [–r] [–y] […] [name […]]
DESCRIPTIONThe wunstmn command uninstalls Tivoli Management Framework files from specified managed nodes. Removing the Tivoli Management Framework files removes the managed node from your Tivoli Management Region (TMR).
wunstmn can uninstall nodes that have a working connection to the TMR server. If the managed node has lost its connection, you can specify the use of rexec to remove the files.
You cannot uninstall the TMR server or the system from which you invoke this command.
To remove a managed node that also has Tivoli applications installed, use the wuninst command to remove the applications. Then run wunstmn to remove the managed node.
Without the –A argument, wunstmn removes only the client database. The –A removes all files associated with the Tivoli Management Framework, including libraries, binaries, manual pages, and so on. The wunstmn command is located in the $bindir/TAS/UNINST directory.
Note: Do not use the –A argument if the managed node you are removing shared files with nodes that you want to keep in your Tivoli environment.
After wunstmn removes the installed files, it invokes wrmnode to remove all entries to this node from the remaining Tivoli databases. After wunstmn completes, run wchkdb to synchronize the Tivoli databases.
Authorization
super
wunstmn
Tivoli Management Framework Reference Manual 1–493
Com
mands
Arguments
–A Removes all Tivoli files from the specified managed node. This includes libraries, binaries, manual pages, message catalogs, and so on. Without this argument, wunstmn removes only the client database of the specified managed node.
–f Specifies that the name argument is a file name containing a list of managed nodes to be uninstalled. The file format is as follows:
ManagedNode_name username
–r Uses rexec as a communication protocol. Use this argument to uninstall a managed node when the oserv is not running.
–y Suppresses confirmation. This argument allows wunstmn to run unattended on multiple managed nodes.
name Specifies either the name of a single managed node to uninstall or the name of a text file containing multiple nodes to uninstall. If used with the –f argument, name specifies the path to a text file. You can specify multiple file names. Without the –f argument, name is the name of a single managed node.
EXAMPLES
1. The following example removes the Tivoli Management Framework and all files from node iandu-4:
wunstmn -A iandu-4
2. The following example uses a file called nodelist to uninstall a group of managed nodes. The –y argument suppresses the confirmation. Because the –A is omitted, only the databases are removed. All Tivoli Management Framework files remain on the nodes.
wunstmn -f -y nodelist
wunstmn
1–494 Version 3.7
SEE ALSOwuninst, wrmnode, wchkdb
wunsub
Tivoli Management Framework Reference Manual 1–495
Com
mands
wunsub Removes Tivoli resources from a profile manager’s subscription list.
SYNOPSISwunsub [–a] [–l] [–r] name [subscriber…]
DESCRIPTIONThe wunsub command removes the Tivoli resources specified in subscriber from the subscription list of the profile manager specified in name.
If the –l argument is specified, any configuration information distributed to the subscriber databases from this profile is maintained in the subscriber’s database, but is made local to the subscriber. If –l is not specified, configuration information in the subscriber that was distributed from the profile specified by name is deleted from the subscriber’s database.
Note: For Tivoli Distributed Monitoring, configuration information is also deleted from the subscriber’s configuration files.
If the –a argument is specified, all current subscribers are removed.
Authorization
super, senior, admin
Arguments
–a Removes all current subscribers to the specified profile manager.
–l Specifies to maintain subscriber’s database, but make it local.
–r Specifies that the wunsub command returns an error code (1) if any of the subscribers were unreachable. A failure code is always returned if the specified subscriber does not exist.
wunsub
1–496 Version 3.7
name The name of the profile manager from which to unsubscribe the resources. Valid formats for the name option include:
■ prof_manager_name
■ @ProfileManager:prof_manager_name
■ /Regions/PolicyRegionName/prof_manager_name
subscriber… The names of the Tivoli resources to remove from the specified profile manager’s subscription list. This option can be specified multiple times. Valid formats for the subscriber option include:
■ @node_name
■ @ManagedNode:node_name
■ @Endpoint:ep_label
■ /Regions/PolicyRegionName/node_name
EXAMPLES
1. The following example unsubscribes all subscribers of profile manager pm1, maintaining configuration information in the subscribers databases as local:
wunsub -a -l pm1
2. The following example unsubscribes subscribers pm2 and mn1 from profile manager pm1. All configuration information is deleted from the subscribers databases.
wunsub pm1 @ProfileManager:pm2 @ManagedNode:mn1
SEE ALSOwcrtprf, wcrtprfmgr, wgetsub, wlssub, wpopulate, wgetprf, wdistrib, wsub, wvalidate
wupdate
Tivoli Management Framework Reference Manual 1–497
Com
mands
wupdate Updates resources in the local name registry.
SYNOPSISwupdate [–f] –r resource [–r resource…] TMRs…
DESCRIPTIONThe wupdate command updates resources in the local name registry from one or more remote Tivoli Management Regions (TMRs). When the wupdate command is run, resources are locked in the name registry. In some cases, the resource may already be locked, such as when another wupdate is running. The wupdate command will attempt to lock a resource for 60 seconds before timing out.
Authorization
senior or super in TMR
Arguments
–f Forces the update regardless of time stamp.
–r resource… Specifies one or more resource types to be updated. You can specify the resource type or use All to update all resource types.
TMRs… Specifies one or more TMRs from which to update. You can specify the TMR name or use All to update all TMRs..
EXAMPLES
1. The following example updates the local name registry with the NisDomain resource type from the ceridwen-Region:
wupdate -r NisDomain ceridwen-Region
2. The following example updates the local name registry with all resource types from the ceridwen-Region and the meiron-Region:
wupdate -r All ceridwen-Region meiron-Region
wupdate
1–498 Version 3.7
3. The following example updates the local name registry with the ProfileManager and AdministratorCollection resource types from all connected TMRs.
wupdate -r ProfileManager -r AdministratorCollection All
4. The following example forces the update for all resource types regardless of the time stamps on the resource types.
wupdate -f -r All meiron-Region
SEE ALSOwconnect, wdisconn, wlsconn
wvalidate
Tivoli Management Framework Reference Manual 1–499
Com
mands
wvalidate Validates a profile against its validation policy.
SYNOPSISwvalidate name
DESCRIPTIONThe wvalidate command validates the profile identified by name against its validation policy.
Authorization
super, senior, admin
Argument
name The profile whose policy is to be validated. Valid formats for the name option include:
■ @prof_name
■ @ProfileManager:prof_name
■ /Regions/PolicyRegionName/prof_manager_name/prof_name
EXAMPLESThe following example validates the profile pr1 against the validation policy:wvalidate @TestProfile:pr1
SEE ALSOwcrtprf, wcrtprfmgr, wgetsub, wlssub, wpopulate, wgetprf, wdistrib, wsub, wunsub
wxterm
1–500 Version 3.7
wxterm Opens an Xterminal window on a specified display.
SYNOPSISwxterm –h node_name [xterm_options]
DESCRIPTIONThe wxterm command opens an Xterminal window on a specified managed node. You can also supply configuration options as you would if you invoked the xterm program directly. If you do not supply configuration options, wxterm uses the default configuration options located in install_dir/bin/interp/TAS/xterm.sh.
Authorization
senior, super
Arguments
–h node_name Specifies the managed node where the xterm program is run.
xterm_options Specifies options that are passed to the xterm program (such as default font, colors, and so on).
Tivoli Management Framework Reference Manual 2–1
2T
ivoli-Defined P
olicy
2Tivoli-Defined Policy
Tivoli Management Framework uses default and validation policy in the task library and profile manger. These services use default and validation methods that call shell scripts to set or validate data. You can edit any of the shell scripts to create custom policies for your organization.
Tivoli endpoint gateways and endpoint managers also use policy scripts. The endpoint scripts differ from the default and validation policy in that policy objects are associated with the endpoint scripts. For additional information about endpoint policy, see “Endpoint Policy” on page -6.
Profile Manager PolicyTivoli Management Framework provides default and validation policy for the profile manager service.
The profile manager default policy defines which managed nodes can become subscribers to a profile manager and defines the profile managers into which a profile can be cloned.
The validation policy validates the following:
■ Whether a subscriber can be removed from a profile manager
■ Whether a profile manager can cancel a subscription
■ Whether a subscriber can be added to a profile manager
■ Whether a profile manager can subscribe to another profile manager
Profile Manager Policy
2–2 Version 3.7
Default Policy MethodsThe following table contains the profile manager default policy methods and their purpose.
Validation Policy MethodsThe following table contains the profile manager validation policy methods and their purpose.
Method Description
pm_def_profile_managers Provides a list of profile managers into which a profile can be cloned
pm_def_subscribers Provides a list of managed nodes that can become subscribers to a profile manager
Method Description
pm_val_remove_subscribers Validates the removal of subscribers from a profile manager
pm_val_remove_subscription Validates the cancellation of a subscription to a profile manager
pm_val_subscribers Validates the addition of subscribers to a profile manager
pm_val_subscription Validates the subscription of a profile manager to another profile manager
Task Library Policy
Tivoli Management Framework Reference Manual 2–3
Tivoli-D
efined Policy
Task Library PolicyWithin the task library, default policy sets the list of managed nodes and profiles managers that are associated with a task or job when it is created.
Validation policy verifies that existing tasks or jobs are associated with the correct managed nodes and profile managers, and that the effective group and user IDs under which the task or job will run are valid.
Default Policy MethodsThe following table contains the task library default policy methods and their purpose.
Method Description
tl_def_dist_mode Provides the default mode for distributing task binaries throughout a TMR
tl_def_man_nodes Provides a default list of managed nodes for a task library
tl_def_prof_mgrs Provides a default list of profile managers for a task library
Editing Profile Manager and Task Library Policy
2–4 Version 3.7
Validation Policy MethodsThe following table contains the task library validation policy methods and their purpose.
Editing Profile Manager and Task Library PolicyThe following example demonstrates the process for editing task library validation policy. You can use the same procedures for editing profile manager validation policy. To edit default policy, replace the –v option with the –d option on the wlspolm, wgetpolm, and wputpolm commands.
As shipped, the task library policy sets the valid managed nodes on which a job or task can be run to all managed nodes in the Tivoli Management Region (TMR). By modifying the validation policy, you can limit the managed nodes on which the job or task actually executes.
1. Enter the following command to return the list of available validation policies and their proper names:
wlspol -v TaskLibrary
2. Enter the following command to get the policy shell script associated with the validate_execution_managed_nodes method and redirect it to a file named aef. You must use the proper name.
wgetpolm -v TaskLibrary BasicTaskLibrary \ tl_val_man_nodes> aef
Method Description
tl_def_man_nodes Validates the list of target managed nodes on which a task or job will execute
tl_def_prof_mgrs Validates the list of target profile managers associated with a task or job
tl_val_set_gid Validates the effective group ID assigned to a task or job
tl_val_set_uid Validates the effective user ID assigned to a task or job
Editing Profile Manager and Task Library Policy
Tivoli Management Framework Reference Manual 2–5
Tivoli-D
efined Policy
The aef file contains a shell script similar to the following:
#!/bin/sh########################################################### $Id: tl_val_man_nodes.sh,v 1.2 1998/09/09 15:41:23 paul$## This script implements the#"validate_execution_managed_nodes" policy# method for the Task Library. The script is provided with# the name of the task, the label of the Admin and all of# the# managed nodes selected for execution targets of the task.# Modify the code below if you want something different# returned.## To debug your changes, you could add the lines:## set -xv# exec > /tmp/debug.output 2>&1## These lines will allow you to see any errors that occur# by looking in the /tmp/debug.output file.## NOTE: This script can also be called when a check_policy# operation is performed. In that case, the name of# the# Admin will be "any". Make sure that you handle# that# case if you modify this script.##########################################################
task_name=$1administrator=$2shift 2
## Example of how to validate the list of managed nodes. ##
# for i in $*; do# if [ $i = "the evil managed node" ]; then# echo FALSE# exit 0# fi# done
echo TRUEexit 0
Endpoint Policy
2–6 Version 3.7
3. Use a text editor to modify the aef file.
Tivoli provides a policy option to limit the managed node on which the job or task executes. To use this option, remove the comment lines from the policy option Tivoli provides and replace “the evil managed node” with the name of a managed node.
You can also add your own options.
4. Enter the following command to replace the policy with the edited policy script.
wputpolm -d TaskLibrary BasicTaskLibrary \tl_val_man_nodes < aef
Use the following command to create your own policy group.
wcrtpol -d TaskLibrary “Secure Tasks”
You can then get or set methods on this new group, and assign the group to the TaskLibrary resource with the Managed Resource Policies dialog.
The methods call shell scripts that you can modify to set a new default policy. You can set default policy on a per policy region basis.
Endpoint PolicyEndpoint policy scripts can be any type of executable file that accepts command line arguments, exits with a return code, and sends output to standard output. In most cases, a shell script is sufficient, although some situations might require a more flexible programming language, such as C. The run time of these scripts (excluding login_policy) affects the amount and efficiency of logins that the endpoint manager can process at one time.
The following table contains the endpoint policy scripts and a description of where and when the script is run.
Endpoint Policy
Tivoli Management Framework Reference Manual 2–7
Tivoli-D
efined Policy
allow_install_policy The allow_install_policy script validates whether an endpoint should exist in the current TMR. The default behavior of this policy allows endpoints to log in unconditionally (the default is exit 0). You can also use this script to perform other processes before the endpoint is logged in. Remember, though, that the endpoint does not exist at the time this script is run. The script cannot, therefore, execute commands that reference the endpoint.
If the script fails, the installation process is terminated and no information is written to the Tivoli database.
Policy Name Origin Execution Time
allow_install_policy Executed by the endpoint manager.
Executed when the endpoint installation begins.
after_install_policy Executed by the endpoint manager.
Executed after the endpoint’s existence is recorded by the endpoint manager and before the endpoint receives its initial login information.
login_policy Executed by the gateway.
Executed each time the endpoint logs in.
select_gateway_policy Executed by the endpoint manager.
Executed each time an endpoint needs to be assigned to a gateway.
Endpoint Policy
2–8 Version 3.7
SYNOPSIS
The endpoint manager runs allow_install_policy when it receives an endpoint’s initial login packet from a gateway. The script is not run on subsequent logins. allow_login_policy is run before the select_gateway_policy script. The synopsis of the command is as follows:
allow_install_policy LCF_DUPL_OBJECT LCF_DUPL_ADDRESS LCF_DUPL_LOGIN LCF_DUPL_GATEWAY LCF_DUPL_INV_ID LCF_DUPL_INTERP ep_label ep_oid ep_interp gw_oidep_ipaddr region dispatcher version
where:
LCF_DUPL_OBJECT Specifies the object ID of the existing endpoint.
LCF_DUPL_ADDRESS Specifies the network address of the existing endpoint.
LCF_DUPL_LOGIN Specifies the timestamp of the existing endpoint’s first normal login.
LCF_DUPL_GATEWAY Specifies the object ID of the existing endpoint’s gateway.
LCF_DUPL_INV_ID Specifies the inventory ID of the existing endpoint.
LCF_DUPL_INTERP Specifies the interp of the existing endpoint.
ep_label Specifies the label of the endpoint trying to log in.
ep_oid Specifies the object ID of the endpoint.
ep_interp Specifies the interpreter type of the endpoint.
gw_oid Specifies the object ID of the intercepting gateway.
ep_ipaddr Specifies the Internet Protocol (IP) address and port number of the endpoint.
region Specifies the region number in which the endpoint resides.
Endpoint Policy
Tivoli Management Framework Reference Manual 2–9
Tivoli-D
efined Policy
dispatcher Specifies the object dispatcher number of the endpoint.
version Specifies the current version of the endpoint software.
unique_id Specifies the unique ID (also called the inventory ID) of the endpoint.
protocol Specifies the network protocol used by the endpoint.
EXAMPLE
The following is an example of the allow_install_policy script. This example does not allow endpoints on the subnet 146.84.26 to log in to the TMR. It also does not allow endpoints that have the string dev in their name.
This script is intended for UNIX systems. For Windows NT, the awk utility does not support all the capabilities of the awk utility on UNIX. In particular, awk ‘{FS=”.” ; print $2}
works to set a period as a record separator on UNIX, but on Windows NT it does not. For Windows NT, awk requires this syntax:
awk -F'.' '{ print $2 }
Note: The endpoint label identified in the following example is the lcfd proposed label and is almost always the host name, which could be fully qualified (spot.dev.tivoli.com) or not (spot). You can change the label with the –Dlcs.machine_name=name option. See the command lcfd for more information.
#!/bin/sh## The following are the command line arguments passed to# this script from the Endpoint Manager.## $1 - The label of the endpoint machine# $2 - The object reference of the endpoint machine# $3 - The interpreter type of the endpoint machine# $4 - The object reference of the gateway that intercepted# the endpoint’s login request# $5 - The IP address of the endpoint logging in# $6 - Region# $7 - Dispatcher# $8 - Version
Endpoint Policy
2–10 Version 3.7
# $9 - The inventory id of the endpoint logging in##The following command line argument will be passed to this script from the ENdpoint Manager, when complied with the MULTIPROTO flag turned on# $10 - The protocol of the endpoint logging in.# TCPIP -> TCP/IP# IPX -> IPX/SPX## During the execution of this script, the endpoint does not# yet formally exist. Therefore, the value of the endpoint# object reference is OBJECT_NIL and the object dispatcher# number is 0. The value of the endpoint label is suggested# by the endpoint (or the user through lcfd -n), but can# only become the final label if the value is not already# taken by another endpoint.set -e
## Don’t allow endpoints from subnet 26 log into this TMR.#
SUBNET=‘echo $5 | awk ’{FS="."}{ print $1"."$2"."$3 }’‘if [ "$SUBNET" = "146.84.26" ]; then
exit 1fi
## Don’t allow endpoints whose name contain the regular# expression "dev".## This line will force the script to exit nonzero if the# expression "dev" is in the label.#echo $1 | grep -v dev
exit 0
after_install_policyThe after_install_policy script performs any processing you want immediately after the endpoint has been created. This policy is run only after the initial login; it is not run on subsequent logins.
The failure of this script does not stop the login process. The endpoint already exists when this script is run. Only the post-processing specified in the script fails.
Endpoint Policy
Tivoli Management Framework Reference Manual 2–11
Tivoli-D
efined Policy
SYNOPSIS
The endpoint manager runs after_install_policy immediately following the initial gateway assignment but before the endpoint login method returns to the intercepting gateway. Because this occurs before the endpoint’s first normal login, you cannot run downcalls from this script. The synopsis of the command is as follows:
after_install_policy ep_label ep_oid ep_interp gw_oid ep_ipaddr region dispatcher version
where:
ep_label Specifies the label of the endpoint for which the script will run.
ep_oid Specifies the object ID of the endpoint.
ep_interp Specifies the interpreter type of the endpoint.
gw_oid Specifies the object ID of the assigned gateway.
ep_ipaddr Specifies the IP address and port number of the endpoint.
region Specifies the region number in which the endpoint resides.
dispatcher Specifies the object dispatcher number of the endpoint.
version Specifies the current version of the endpoint software.
unique_id Specifies the unique ID (also called the inventory ID) of the endpoint.
protocol Specifies the network protocol used by the endpoint.
EXAMPLE
The following example subscribes new endpoints to a profile manager that represents endpoints of similar architecture types. If the policy region or profile manager does not exist, the policy creates it.#!/bin/sh
## The following are the command line arguments passed to# this script from the Endpoint Manager.## $1 - The label of the endpoint machine
Endpoint Policy
2–12 Version 3.7
# $2 - The object reference of the endpoint machine# $3 - The interpreter type of the endpoint machine# $4 - The object reference of the assigned gateway that the# endpoint logged into# $5 - The IP address of the endpoint logging in# $6 - Region# $7 - Dispatcher# $8 - Version# $9 - The inventory id of the endpoint logging in##The following command line argument will be passed to this script from the ENdpoint Manager, when complied with the MULTIPROTO flag turned on# $10 - The protocol of the endpoint logging in.# TCPIP -> TCP/IP# IPX -> IPX/SPX
LCF_POLICY_REGION=LCF-EndpointsPROFILE_MANAGER=LCF-$3EP=$1
## Check to see if our top-level policy region already# exists. If not create it and put it on this administrators# desktop.## Disable "exit on error" for this call since we will handle# the failure.#set +ewlookup -r PolicyRegion $LCF_POLICY_REGION > /dev/nullERR=$?set -e
if [ $ERR -ne 0 ]; thenALI=‘objcall 0.0.0 get_security_objid‘set ‘objcall $ALI get_identity‘ADMIN="$1"ADMIN_OID=‘echo $2 |cut -d”#” -f1‘wcrtpr -m ProfileManager -a $ADMIN $LCF_POLICY_REGIONidlcall $ADMIN_OID refresh_collection
fi
## Check to see if our interp specific profile manager# already exists. If not create it and make it dataless so# that we can subscribe the endpoint to it.## Disable "exit on error" for this call since we will handle# the failure.
Endpoint Policy
Tivoli Management Framework Reference Manual 2–13
Tivoli-D
efined Policy
#set +ewlookup -r ProfileManager $PROFILE_MANAGER > /dev/nullERR=$?set -e
if [ $ERR -ne 0 ]; thenwcrtprfmgr $LCF_POLICY_REGION $PROFILE_MANAGER > /dev/nullwsetpm -d /Library/ProfileManager/$PROFILE_MANAGER
fi
## Subscribe the endpoint to the profile manager which# contains the endpoints for that specific interp type.#wsub /Library/ProfileManager/$PROFILE_MANAGER \@Endpoint:$EP
exit 0
login_policyThe login_policy script performs any processing you want each time an endpoint logs in. This policy is run by the gateway to which the endpoint is assigned. The same policy script is run on all of the gateways in a TMR.
Note: This policy does not support the use of binaries.
One feature of this script is that it can be configured to automatically upgrade the endpoint software on each client. To configure the login_policy script to upgrade endpoint software, follow these steps:
1. Enable the upgrade script (upgrade.sh) in $BINDIR/../lcf_bundle/upgrade by changing the upgrade_mode entry to auto in the upgrade.cntl file. This step must be performed on a per gateway basis.
2. Edit the login_policy script to call upgrade.sh. The following example script includes this option. The upgrade script does not log output unless defined to do so.
Endpoint Policy
2–14 Version 3.7
SYNOPSIS
The endpoint gateway runs login_policy each time an endpoint logs in. The synopsis of the command is as follows:
login_policy ep_label ep_oid ep_interp gw_oid ep_ipaddr region dispatcher version
where:
ep_label Specifies the label of the endpoint for which the script will run.
ep_oid Specifies the object ID of the endpoint.
ep_interp Specifies the interpreter type of the endpoint.
gw_oid Specifies the object ID of the assigned gateway.
ep_ipaddr Specifies the IP address and port number of the endpoint.
region Specifies the region number in which the endpoint resides.
dispatcher Specifies the object dispatcher number of the endpoint.
version Specifies the current version of the endpoint software.
unique_id Specifies the unique ID (also called the inventory ID) of the endpoint.
protocol Specifies the network protocol used by the endpoint.
EXAMPLE
The following example logs a notice to an endpoint related notice group every time an endpoint logs in and automatically upgrades the endpoint software:#!/bin/sh## The following are the command line arguments passed to# this script from the Endpoint Manager.## $1 - The label of the endpoint machine# $2 - The object reference of the endpoint machine# $3 - The interpreter type of the endpoint machine# $4 - The object reference of the assigned gateway that the# endpoint logged into# $5 - The IP address of the endpoint logging in
Endpoint Policy
Tivoli Management Framework Reference Manual 2–15
Tivoli-D
efined Policy
# $6 - Region# $7 - Dispatcher# $8 - Version## AUTO UPGRADE# Invoke the upgrade script to check the current version of# the endpoint software and upgrade if necessary.BO=‘objcall 0.0.0 self‘OS=‘objcall $BO getattr oserv‘INSTALLDIR=`objcall $OS query install_dir|tr '\134'’ '/'`$INSTALLDIR/lcf_bundle/upgrade/upgrade.sh $1 $8 $3
#LCF_NOTICE_GROUP=LCF_Endpoints## Send a notice to LCF endpoint notice group every time this# endpoint logs in.#
set +ewlookup -r TMF_Notice $LCF_NOTICE_GROUP > /dev/nullERR=$?set -e
if [ $ERR -ne 0 ]; thenNTFGM=`wlookup -r Classes TMF_Notice`idlcall -T top $NTFGM \
TMF_Notice::NoticeManager::create_notice_group \'"'$LCF_NOTICE_GROUP'" 72'
fi
GW=`idlcall $4 _get_label`EPOID=`wlookup -o -r Endpoint $1`
wsndnotif $LCF_NOTICE_GROUP Notice << LCF_NOTICEEndpoint $1 ($EPOID of interp type, $3, logged into gateway$GW ($4).LCF_NOTICE
exit 0
select_gateway_policyThe select_gateway_policy script determines the set of gateways that are allowed to manage the endpoint. select_gateway_policy is run at initial login, when an endpoint is isolated, or when an endpoint performs a migratory login.
Endpoint Policy
2–16 Version 3.7
If the script does not return gateways, the endpoint manager performs its default selection process and generates a list of up to five gateways in the endpoint’s region. The endpoint manager’s default selection process is overridden by select_gateway_policy. If this policy is not defined, the intercepting gateway is added to the end of the list of candidate gateways.
The intercepting gateway is also added to the end of the select_gateway_policy list to ensure that the endpoint has at least one definite contact. If the endpoint manager cannot contact any of the gateways listed in the script, the endpoint manager assigns the intercepting gateway to the endpoint. If the script fails (returns nonzero), the login attempt fails. If select_gateway_policy runs successfully, the object ID of the assigned gateway is passed to the endpoint.
SYNOPSIS
The endpoint manager runs select_gateway_policy when it receives the endpoint’s login packet. The synopsis of the command is as follows:
select_gateway_policy ep_label ep_oid ep_interp gw_oid ep_ipaddr region dispatcher version
where:
ep_label Specifies the label of the endpoint for which the script will run.
ep_oid Specifies the object ID of the endpoint.
ep_interp Specifies the interpreter type of the endpoint.
gw_oid Specifies the object ID of the assigned gateway.
ep_ipaddr Specifies the IP address of the endpoint.
region Specifies the policy region in which the endpoint resides.
dispatcher Specifies the object dispatcher number of the endpoint.
version Specifies the current version of the endpoint.
unique_id Specifies the unique ID (also called the inventory ID) of the endpoint.
protocol Specifies the network protocol used by the endpoint.
Endpoint Policy
Tivoli Management Framework Reference Manual 2–17
Tivoli-D
efined Policy
EXAMPLE
The arguments passed to this script from the endpoint manager are the same as the previous three endpoint policy scripts. The variable LCF_LOGIN_STATUS is also set by the endpoint manager. A value of 2 indicates that the endpoint is isolated (unable to contact its assigned gateway). Isolated endpoints are automatically migrated to another gateway unless the select_gateway_policy script terminates with a nonzero exit status. For more information about endpoint isolation or migration, see the Tivoli Management Framework Planning and Deployment Guide.
Note: During the execution of this script, the endpoint does not yet formally exist. Therefore, the value of the endpoint object reference is OBJECT_NIL and the object dispatcher number is 0. The value of the endpoint label is suggested by the endpoint (or the user through lcfd –n), but can only become the final label if the value is not already taken by another endpoint.
If your gateways and endpoints are separated by a network address translation (NAT) device, you must use the fully qualified host name of the gateway appended to its object identifier with a pipe ( | ) symbol. For example, a gateway paris fully qualified as paris.dev.server.com with an object identifier of 123267682.1.529 should be entered in the select_gateway_policy script as follows:123267682.1.529|paris.dev.server.com
The following is an example script:#!/bin/sh## The following are the command line arguments passed to# this script from the Endpoint Manager.## $1 - The label of the endpoint machine# $2 - The object reference of the endpoint machine# $3 - The interpreter type of the endpoint machine# $4 - The object reference of the assigned gateway that the# endpoint logged into# $5 - The IP address of the endpoint logging in# $6 - Region# $7 - Dispatcher# $8 - Version# $9 - The inventory id of the endpoint logging in##The following command line argument will be passed to this script
Endpoint Policy
2–18 Version 3.7
from the ENdpoint Manager, when complied with the MULTIPROTO flag turned on# $10 - The protocol of the endpoint logging in.# TCPIP -> TCP/IP# IPX -> IPX/SPX## Note that the variable LCF_LOGIN_STATUS is also set by the# endpoint manager. A value of 2 indicates the endpoint is # isolated# That is, it is unable to contact its assigned gateway.# Isolated endpoints are automatically migrated to another # gateway# unless the select_gateway_policy terminates with a nonzero # exit# status.
# Also note that during the execution of allow_install_policy # and# select_gateway_policy scripts, the endpoint does not yet # formally# exist. For this reason, the endpoint object reference will # have# a value of OBJECT_NIL and the object dispatcher number will be# 0. The endpoint label will have the value suggested by the# endpoint (or the user via lcfd -n) but is not guaranteed to # become# the final endpoint label. It will become the final endpoint # label# if this value is not already taken by another endpoint.
# only ep_ip is needed for this exampleep_label=$1ep_oid=$2ep_interp=$3gateway=$4ep_ip=$5region=$6dispatcher=$7version=$8#FOUNDONE=FALSE# we just want the subnet of the endpointSUBNET=‘echo $ep_ip|cut -d'.' -f3‘# get all gateways and find ones that are on the same subnetGATEWAYS=`wlookup -ar Gateway -o`
for gwoid in $GATEWAYSdogwproxy=‘idlattr -tg $gwoid proxy Object`mnips=`wifconfig -h $gwproxy | grep -v Device | awk
Endpoint Policy
Tivoli Management Framework Reference Manual 2–19
Tivoli-D
efined Policy
'{print $2}'‘
# a managed node might have multiple interfaces, so check each # of them in the gateway subnet matches the endpoint subnet,# return gwoid if it matchesfor ip in $mnipsdogwsub=`echo $ip | cut -d'.' -f3‘if [ $gwsub -eq $SUBNET ]thenecho $gwoid FOUNDONE=TRUEfidonedone
# if you did not find a gateway, and you still want the endpoint# to log in, exit 0, else exit 1
Editing Endpoint PolicyTivoli Management Framework is installed with empty endpoint policy scripts. To add content to these scripts or, later, to edit existing scripts, you must use the wgeteppol and wputeppol commands. See Chapter 1, “Commands,” for more information about these commands.
Use the following steps to edit one of the defined policy scripts. This example uses the login_policy script. The same procedure works for all the policy scripts by replacing login_policy with the name of the policy you want to edit.
Note: If you do not redirect the policy to a file, the policy is written to your screen.
1. Enter the following command to extract login_policy and write it to a file:
wgeteppol login_policy > login_policy.txt
Profile Manager and Task Library Policy Methods
2–20 Version 3.7
If you are editing this script for the first time, you will see the following output. On subsequent edits, you will see the entire script.
#!/bin/sh## The following are the command line arguments passed# to this script from the gateway.## $1 - The label of the endpoint machine# $2 - The object reference of the endpoint machine# $3 - The interpreter type of the endpoint machine# $4 - The object reference of the gateway that the# endpoint logged into# $5 - The IP address of the endpoint logging in# $6 - Region# $7 - Dispatcher# $8 - Version# $9 - The inventory id of the endpoint logging in##The following command line argument will be passed to this script from the ENdpoint Manager, when complied with the MULTIPROTO flag turned on# $10 - The protocol of the endpoint logging in.# TCPIP -> TCP/IP# IPX -> IPX/SPX
exit 0#
2. Use a text editor to add the contents of the script or to modify existing content.
3. Enter the following command to return the updated policy script:
wputeppol login_policy < login_policy.txt
Profile Manager and Task Library Policy MethodsThe remainder of this chapter contains the profile manager and task library policy method reference pages.
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–21
Tivoli-D
efined Policy
pm_def_profile_managersProvides a list of profile managers into which a profile can be cloned.
RESOURCEProfileManager
SYNOPSISpm_def_profile_managers mgr_name
COMMENTSThe pm_def_profile_managers method provides a list of profile managers into which a profile can be cloned.
The method runs the pm_def_profile_managers script. The script writes the profile manager list to standard output, one profile manager per line. The output, in the format label OID, is displayed in the Clone to Profile Managers scrolling list in the Clone Profile dialog.
The default implementation of pm_def_profile_managers returns a list of all instances in all TMRs of the ProfileManager resource type.
Arguments
mgr_name Specifies the name of the profile manager containing the profile to clone.
RETURN CODESThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes label OID… to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
Profile Manager and Task Library Policy Methods
2–22 Version 3.7
pm_def_subscribers Provides a list of managed nodes that can become subscribers to a profile manager.
RESOURCEProfileManager
SYNOPSISpm_def_subscribers mgr_name
COMMENTSThe pm_def_subscribers method provides a list of managed nodes, profile managers, and endpoints that can become subscribers to a profile manager.
The method runs the pm_def_subscribers script. The script writes the subscriber list to standard output, one subscriber per line. The output, in the format label OID, is displayed in the Available to become Subscribers scrolling list in the Subscriber dialog.
The default implementation of pm_def_subscribers returns a list of all instances in all TMRs of the ProfileManager, and ManagedNode resource types.
Arguments
mgr_name Specifies the name of the profile manager that is to be subscribed to.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes label OID… to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–23
Tivoli-D
efined Policy
RESOURCEpm_val_remove_subscribers, pm_val_remove_subscription, pm_val_subscribers, pm_val_subscription
Profile Manager and Task Library Policy Methods
2–24 Version 3.7
pm_val_remove_subscribersValidates the removal of subscribers from a profile manager.
RESOURCEProfileManager
SYNOPSISpm_val_remove_subscribers mgr_name action subscriber…
COMMENTSThe pm_val_remove_subscribers method validates the removal of subscribers from a profile manager.
The method runs the pm_val_remove_subscribers script. The script writes TRUE to standard output if the removal meets the validation criteria, FALSE if it does not.
Tivoli provides the default value of TRUE.
Arguments
mgr_name Specifies the name of the profile manager.
action Indicates the action that will be taken when removing the subscribers. This parameter must be one of the following keywords: localize, delete.
subscriber… Specifies the list of subscribers being removed. Separate each subscriber with a space.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–25
Tivoli-D
efined Policy
RESOURCEpm_val_remove_subscription, pm_val_remove_subscribers, pm_val_subscription
Profile Manager and Task Library Policy Methods
2–26 Version 3.7
pm_val_remove_subscriptionValidates the cancellation of a subscription to a profile manager.
RESOURCEProfileManager
SYNOPSISpm_val_remove_subscription subscriber action mgr_name
COMMENTSThe pm_val_remove_subscription method validates the cancellation of a subscription to a profile manager by a profile manager or endpoint. The method runs the pm_val_remove_subscription script. The script writes TRUE to standard output if the removal meets the validation criteria, FALSE if it does not. Tivoli provides the default value of TRUE.
Arguments
subscriber Specifies the name of the profile manager or endpoint that is the subscriber.
action Indicates the action that will be taken when removing the subscription. This parameter must be one of the following keywords: localize, delete.
mgr_name Specifies the profile manager to which the subscriber subscribes.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–27
Tivoli-D
efined Policy
RESOURCEpm_val_remove_subscribers, pm_val_remove_subscription, pm_val_subscription
Profile Manager and Task Library Policy Methods
2–28 Version 3.7
pm_val_subscribersValidates the addition of subscribers to a profile manager.
RESOURCEProfileManager
SYNOPSISpm_val_subscribers mgr_name subscriber…
COMMENTSThe pm_val_subscribers method validates the addition of subscribers to a profile manager. The method runs the pm_val_subscribers script. The script writes TRUE to standard output if the new subscribers meet the validation criteria, FALSE if they do not. Tivoli provides the default value of TRUE.
Arguments
mgr_name Specifies the name of the profile manager.
subscriber Specifies the list of new subscribers to validate. Separate each subscriber with a space.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
RESOURCEpm_val_remove_subscribers, pm_val_remove_subscription, pm_val_subscription
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–29
Tivoli-D
efined Policy
pm_val_subscriptionValidates the addition of a subscription of a profile manager to another profile manager.
RESOURCEProfileManager
SYNOPSISpm_val_subscription subscribee mgr_name
COMMENTSThe pm_val_subscription method validates the addition of a subscription to a profile manager by a profile manager or endpoint. The method runs the pm_val_subscription script. The script writes TRUE to standard output if the subscription meets the validation criteria, FALSE if it does not. Tivoli provides the default value of TRUE.
Arguments
subscribee Specifies the profile manager that is the subscribee.
mgr_name Specifies the profile manager or endpoint that is the subscriber.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
RESOURCEpm_val_remove_subscribers, pm_val_remove_subscription, pm_val_subscription
Profile Manager and Task Library Policy Methods
2–30 Version 3.7
tl_def_dist_mode Provides the default mode for distributing task binaries throughout a Tivoli Management Region (TMR).
RESOURCETaskLibrary
SYNOPSIStl_def_dist_mode
COMMENTSThe tl_def_dist_mode method provides the default mode used to distribute task executable files when a task is created. The following are valid distribution modes:
ALI Copies task binaries to the TMR server only.
LOCAL Copies task binaries to all managed nodes in the local TMR.
GLOBAL Copies task binaries to all managed nodes in all connected TMRs.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method.
1 Indicates that the method was invoked with invalid parameters.
2 Indicates an error.
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–31
Tivoli-D
efined Policy
tl_def_man_nodes Provides a default list of managed nodes for a task library.
RESOURCETaskLibrary
SYNOPSIStl_def_man_nodes task_name admin_name
COMMENTSThe tl_def_man_nodes method provides a default list of managed nodes and endpoints for a task library. The tl_def_man_nodes method runs the tl_def_man_nodes.sh script. This script must provide a list of ManagedNode and Endpoint resources where the task can run.
The method writes the list of managed nodes and endpoints to standard output, one node per line.
Arguments
task_name Specifies the task for which the list is being generated.
admin_name Specifies the name of the administrator that invoked the method.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method.
1 Indicates that the method was invoked with invalid parameters.
2 Indicates an error.
RESOURCEtl_def_prof_mgrs
Profile Manager and Task Library Policy Methods
2–32 Version 3.7
tl_def_prof_mgrs Provides a default list of profile managers for a task library.
RESOURCETaskLibrary
SYNOPSIStl_def_prof_mgrs task_name admin_name
COMMENTSThe tl_def_prof_mgrs method provides a default list of profile managers for a task library. This script must provide a list of ProfileManager resources where the task can run.
The method writes the list of profile managers to standard output, one per line.
Arguments
task_name Specifies the task for which the list is being generated.
admin_name Specifies the name of the administrator that invoked the method.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method.
1 Indicates that the method was invoked with invalid parameters.
2 Indicates an error.
RESOURCEtl_val_man_nodes
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–33
Tivoli-D
efined Policy
tl_val_man_nodes Validates the list of target managed nodes associated with a task or job.
RESOURCETaskLibrary
SYNOPSIStl_val_man_nodes task_name admin_name node_name…
COMMENTSThe tl_val_man_nodes method validates the list of managed nodes and endpoints associated with a task or job.
The script writes TRUE to standard output if the list meets the validation criteria, FALSE if it does not.
Tivoli provides the default value of TRUE.
Arguments
task_name Specifies the name of the task or job.
admin_name Specifies the name of the administrator that invoked the method.
node_name… Specifies the list of managed nodes and endpoints to validate. Separate each name with a space.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
RESOURCEtl_def_prof_mgrs, tl_val_set_gid, tl_val_set_uid
Profile Manager and Task Library Policy Methods
2–34 Version 3.7
tl_val_prof_mgrs Validates the list of target profile managers associated with a task or job.
RESOURCETaskLibrary
SYNOPSIStl_val_prof_mgrs task_name admin_name mgr_name…
COMMENTSThe tl_val_prof_mgrs method validates the list of target profile managers associated with a task or job.
The script writes TRUE to standard output if the list meets the validation criteria, FALSE if it does not. The default value is TRUE.
Arguments
task_name Specifies the name of the task or job.
admin_name Specifies the name of the administrator that invoked the method.
mgr_name… Specifies the list of profile managers to validate. Separate each profile manager’s name with a space.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
RESOURCEtl_def_man_nodes, tl_val_set_gid, tl_val_set_uid
Profile Manager and Task Library Policy Methods
Tivoli Management Framework Reference Manual 2–35
Tivoli-D
efined Policy
tl_val_set_gid Validates the group ID assigned to a task or job.
RESOURCETaskLibrary
SYNOPSIStl_val_set_gid admin_name group_id
COMMENTSThe tl_val_set_gid method validates the group ID associated with a task or job.
The script writes TRUE to standard output if the group ID meets the validation criteria, FALSE if it does not.
Tivoli provides the default value of TRUE.
Arguments
admin_name Specifies the name of the administrator that invoked the method.
group_id Specifies the group ID to validate.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
RESOURCEtl_def_man_nodes, tl_val_set_gid, tl_val_set_uid
Profile Manager and Task Library Policy Methods
2–36 Version 3.7
tl_val_set_uid Validates the user ID assigned to a task or job.
RESOURCETaskLibrary
SYNOPSIStl_val_set_uid admin_name user_id
COMMENTSThe tl_val_set_uid method validates the user ID associated with a task or job.
The script writes TRUE to standard output if the user ID meets the validation criteria, FALSE if it does not.
Tivoli provides the default value of TRUE.
Arguments
admin_name Specifies the name of the administrator that invoked the method.
user_id Specifies the user ID to validate.
RESOURCEThis method exits with one of the following:
0 Indicates the successful completion of the method; the method writes either TRUE or FALSE to standard output.
1 Indicates that the method exited with an error. The method’s standard output is undefined.
RESOURCEtl_def_man_nodes, tl_val_prof_mgrs, tl_val_set_gid
Tivoli Management Framework Reference Manual Index–1
Index
Symbols.aof files 1-299, 1-302, 1-305.cdf files 1-299, 1-302, 1-305.gdf files 1-299, 1-302, 1-305
Aadding
block of statements into a file 1-284entries to a path statement in a registry
hive 1-120lines to a file 1-286
administrator commands 1-7administrator tag 1-300, 1-303, 1-306AMS groups 1-303, 1-305application
dependency instance 1-305dependency library 1-305distributing 1-299, 1-302installing 1-299, 1-302maintaining 1-299, 1-302, 1-305task library 1-305uninstall 1-489
application description file 1-299, 1-302, 1-305
application management 1-299, 1-302, 1-305
application management package (AMP) 1-299, 1-302, 1-305
Application Management Specification (AMS) 1-299, 1-302, 1-305
CCLI commands
idlarg 1-23idlattr 1-25idlcall 1-27idlexception 1-29idlinput 1-31idlresult 1-32installdir 1-291kadmin 1-34kadmind 1-37kdb_destroy 1-39kdb_edit 1-41kdb_init 1-43kdb_util 1-45kdestroy 1-47kerberos 1-48kinit 1-52klist 1-53kpasswd 1-55ksrvtgt 1-57kstash 1-59lcfd 1-61lcfd.sh 1-71logls 1-72objcall 1-74odadmin 1-77odbls 1-92odstat 1-94oinstall 1-101oserv 1-103setpr 1-236tivoli 1-108tmcmd 1-110tmstat 1-112w4inslcf.pl 1-115waddicon 1-118wadminep 1-122wauthadmin 1-123wbindmsg 1-129wbkupdb 1-125
Index–2 Version 3.7
wbroadcast 1-131wcatcher 1-132wcd 1-134wchkdb 1-135wchknode 1-137wchkpol 1-139wci 1-141wclient 1-150wco 1-160wconnect 1-168wcpcdrom 1-173wcpyfile 1-176wcrtadmin 1-177wcrtgate 1-180wcrtjob 1-182wcrtpol 1-185wcrtpr 1-187wcrtprf 1-189wcrtprfmgr 1-191wcrtqlib 1-192wcrtquery 1-193wcrtrim 1-196wcrttask 1-199wcrttlib 1-202wdate 1-203wdel 1-204wdelep 1-206wdelgate 1-207wdeljob 1-208wdelpol 1-209wdelpr 1-210wdelsched 1-212wdeltask 1-213wdepot 1-214wdisconn 1-217wdiskspace 1-219wdistrib 1-220weditini 1-226wedschd 1-228wenblsched 1-234wep 1-236wexpnotif 1-245
wgateway 1-246wgetadmin 1-250wgetdfpol 1-253wgeteppol 1-255wgetjob 1-257wgetpolm 1-260wgetpr 1-262wgetprf 1-263wgetquery 1-265wgetrim 1-267wgetsched 1-268wgetsub 1-271wgettask 1-272wgetval 1-274whostid 1-276wiconv 1-277wident 1-278widmap 1-279wifconfig 1-282winsline 1-286winstall 1-288winstlcf 1-293winstruct 1-299winstruct_plus 1-302winstruct_task 1-305winterp 1-307wln 1-310wlocalhost 1-312wlocktmr 1-313wlocpath 1-315wlookup 1-317wls 1-319wlsconn 1-321wlsinst 1-324wlsnotif 1-327wlspol 1-330wlspolm 1-331wlssub 1-334wlstlib 1-336wmailhost 1-337wmannode 1-338wmdist 1-339
Tivoli Management Framework Reference Manual Index–3
wmdistgui 1-350wmemsize 1-351wmerge 1-352wmrgini 1-356wmv 1-357wpatch 1-359wping 1-361wpopulate 1-362wputeppol 1-364wputpolm 1-365wpwd 1-369wrcs 1-370wrcsdiff 1-377wrcsmerge 1-379wrefresh 1-381wregister 1-382wrestart 1-384wrlog 1-389wrm 1-393wrmnode 1-395wrplblk 1-397wrplline 1-399wrpt 1-401wrunas 1-409wruninvquery 1-410wrunjob 1-414wrunquery 1-417wruntask 1-419wschedjob 1-424wserver 1-429wsetadmin 1-437wsetdfpol 1-439wseterr 1-440wsetjob 1-441wsetlang 1-444wsetpkey 1-446wsetpm 1-447wsetpr 1-448wsetquery 1-450wsetrim 1-452wsetrimpw 1-454wsettap 1-308, 1-455
wsettask 1-457wsetval 1-459wsndnotif 1-461wstarthttpd 1-463wstartsched 1-464wstophttpd 1-465wsub 1-466wsupport 1-468wtailnotif 1-471wtaskabort 1-473wtemp 1-476wtimezone 1-475wtrace 1-483wuname 1-488wuninst 1-489wunstmn 1-492wunsub 1-495wupdate 1-497wvalidate 1-499wxterm 1-500
command tableadministrator 1-7configuration management 1-8endpoint 1-11httpd 1-9installation 1-9interregion 1-10kerberos 1-10maintenance 1-13managed node 1-15miscellaneous 1-20notification 1-16policy 1-16query 1-17RCS 1-18RIM 1-18scheduler 1-19task library 1-19
commands, using Tivoli 1-1configuration management commands 1-8
Index–4 Version 3.7
Ddefault methods
pm_def_profile_managers 2-21pm_def_subscribers 2-22tl_def_dist_mode 2-30tl_def_man_nodes 2-31tl_def_prof_mgrs 2-32
dependency instance 1-305dependency library 1-305disk space verifying 1-224
Ee-mail
configuring Windows NT 1-337SMTP 1-337specifying server 1-337
endpoint commands 1-11environment variable 1-300, 1-303,
1-306
Hhost
e-mail 1-337SMTP server 1-337
httpd commands 1-9
Iidlarg command 1-23idlattr command 1-25idlcall command 1-27idlexception command 1-29idlinput command 1-31idlresult command 1-32INI file
merging groups and variables from several files 1-356
modifying 1-226installation commands 1-9interregion commands 1-10
Kkadmin command 1-34kadmind command 1-37kdb_destroy command 1-39kdb_edit command 1-41kdb_init command 1-43kdb_util command 1-45kdestroy command 1-47kerberos command 1-48Kerberos commands
kadmin 1-34kadmind 1-37kdb_destroy 1-39kdb_edit 1-41kdb_init 1-43kdb_util 1-45kdestroy 1-47kerberos 1-48kinit 1-52klist 1-53kpasswd 1-55ksrvtgt 1-57kstash 1-59table 1-10
kinit command 1-52klist command 1-53kpasswd command 1-55ksrvtgt command 1-57kstash command 1-59
Tivoli Management Framework Reference Manual Index–5
Llcfd command 1-61lcfd.sh command 1-71libraries
dependency 1-305task 1-305
logls command 1-72Lotus Notes, as Tivoli mail server 1-337
Mmail server
for Tivoli tools 1-337specifying for Windows NT 1-337
maintenance commands, low-level 1-13maintenance, of an application 1-299,
1-302, 1-305managed node commands 1-15management data 1-299, 1-302, 1-305Management Extension Tool Group
(MTEG) 1-302merging groups and variables from INI files
1-356methods
pm_def_profile_managers 2-21pm_def_subscribers 2-22pm_val_remove_subscribers 2-24pm_val_remove_subscription 2-26pm_val_subscribers 2-28pm_val_subscription 2-29tl_def_dist_mode 2-30tl_def_man_nodes 2-31tl_def_prof_mgrs 2-32tl_val_man_nodes 2-33tl_val_prof_mgrs 2-34tl_val_set_gid 2-35tl_val_set_uid 2-36
Microsoft Exchange, as Tivoli mail server 1-337
miscellaneous commands, low-level 1-20modifying groups, variables, and values in an
INI file 1-226module 1-302
Nnotification commands 1-16
Oobjcall command 1-74odadmin command 1-77odbls command 1-92odstat command 1-94oinstall command 1-101oserv command 1-103
Pplatform commands 1-7pm_def_profile_managers method 2-21pm_def_subscribers method 2-22pm_val_remove_subscribers method 2-24pm_val_remove_subscription method 2-26pm_val_subscribers method 2-28pm_val_subscription method 2-29policy
endpoint policyafter_install_policy 2-10allow_install_policy 2-7editing 2-19login_policy 2-13select_gateway_policy 2-15software upgrade option 2-13
policy commands 1-16profile manager
Index–6 Version 3.7
pm_def_profile_managers method 2-21
pm_def_subscribers method 2-22
Qquery commands 1-17
RRCS commands
table 1-18wci 1-141wco 1-160wident 1-278wrcs 1-370wrcsdiff 1-377wrcsmerge 1-379wrlog 1-389
rebooting a system 1-384registry hives
adding an entry 1-120retrieving key values 1-258setting key values 1-459
removingblock statements from a file 1-156lines from a file 1-158
replacingblock of statements in a file 1-397lines in a file 1-399
restarting a system 1-384retrieving registry hive key values 1-258RIM commands 1-18
Sscheduler commands 1-19setting
registry hive key values 1-459return codes from a batch file for a
BARC program 1-440SMTP
connecting to Windows NT 1-337gateway software 1-337mail server 1-337
staging directory 1-300, 1-303, 1-306
Ttask library
commands 1-19, 1-305pm_val_remove_subscribers method
2-24pm_val_remove_subscription method
2-26pm_val_subscribers method 2-28pm_val_subscription method 2-29tl_def_dist_mode method 2-30tl_def_man_nodes method 2-31tl_def_prof_mgrs method 2-32tl_val_man_nodes method 2-33tl_val_prof_mgrs method 2-34tl_val_set_gid method 2-35tl_val_set_uid method 2-36
Tivoli Application Management module 1-302
tivoli command 1-108tl_def_dist_mode method 2-30tl_def_man_nodes method 2-31tl_def_prof_mgrs method 2-32tl_val_man_nodes method 2-33tl_val_prof_mgrs method 2-34tl_val_set_gid method 2-35tl_val_set_uid method 2-36tmcmd command 1-110tmstat command 1-112transactions
hierarchies 1-6
Tivoli Management Framework Reference Manual Index–7
revocable subtransactions 1-6subtransactions 1-6
Vvalidation methods
pm_val_remove_subscribers 2-24pm_val_remove_subscription 2-26pm_val_subscribers 2-28pm_val_subscription 2-29tl_val_man_nodes 2-33tl_val_prof_mgrs 2-34tl_val_set_gid 2-35tl_val_set_uid 2-36
verifying available disk space 1-224
Ww4inslcf.pl command 1-115waddicon command 1-118waddpath command 1-120wadminep command 1-122wauthadmin command 1-123wbindmsg command 1-129wbkupdb command 1-125wbroadcast command 1-131wcatcher command 1-132wcd command 1-134wchkdb command 1-135wchknode command 1-137wchkpol command 1-139wci command 1-141wclient command 1-150wclrblk command 1-156wclrline command 1-158wco command 1-160wconnect command 1-168wcpcdrom command 1-173
wcpyfile command 1-176wcrtadmin command 1-177wcrtgate command 1-180wcrtjob command 1-182wcrtpol command 1-185wcrtpr command 1-187wcrtprf command 1-189wcrtprfmgr command 1-191wcrtqlib command 1-192wcrtquery command 1-193wcrtrim command 1-196wcrttask command 1-199wcrttlib command 1-202wdate command 1-203wdel command 1-204wdelep command 1-206wdelgate command 1-207wdeljob command 1-208wdelpol command 1-209wdelpr command 1-210wdelsched command 1-212wdeltask command 1-213wdepot command 1-214wdisconn command 1-217wdiskspace command 1-219wdistrib command 1-220wdskspc command 1-224weditini command 1-226wedschd command 1-228wenblsch command 1-234wep command 1-236wexpnotif command 1-245wgateway command 1-246wgetadmin command 1-250wgetdfpol command 1-253wgeteppol command 1-255wgetjob command 1-257wgetkey command 1-258
Index–8 Version 3.7
wgetpolm command 1-260wgetpr command 1-262wgetprf command 1-263wgetquery command 1-265wgetrim command 1-267wgetsched command 1-268wgetsub command 1-271wgettask command 1-272wgetval command 1-274whostid command 1-276wiconv command 1-277wident command 1-278widmap command 1-279wifconfig command 1-282Windows NT mail
connecting to SMTP server 1-337SMTP gateway 1-337
winsblk command 1-284winsline command 1-286winstall command 1-288winstdir command 1-291winstlcf command 1-293winstruct command 1-299winstruct_plus command 1-302winstruct_task command 1-305winterp command 1-307wln command 1-310wlocalhost command 1-312wlocktmr command 1-313wlocpath command 1-315wlookup command 1-317wls command 1-319wlsconn command 1-321wlsinst command 1-324wlsnotif command 1-327wlspol command 1-330wlspolm command 1-331wlssub command 1-334wlstlib command 1-336
wmailhost command 1-337wmannode command 1-338wmdist command 1-339wmdistgui command 1-350wmemsize command 1-351wmerge command 1-352wmrgaef command 1-354wmrgini command 1-356wmv command 1-357wpatch command 1-359wping command 1-361wpopulate command 1-362wputeppol command 1-364wputpolm command 1-365wpwd command 1-369wrcs command 1-370wrcsdiff command 1-377wrcsmerge command 1-379wrefresh command 1-381wregister command 1-382wrestart command 1-384wrlog command 1-389wrm command 1-393wrmnode command 1-395wrplblk command 1-397wrplline command 1-399wrpt command 1-401wrunas command 1-409wruninvquery command 1-410wrunjob 1-414wrunquery command 1-417wruntask command 1-419wschedjob command 1-424wserver command 1-429wsetadmin command 1-437wsetdfpol command 1-439wseterr command 1-440wsetjob command 1-441
Tivoli Management Framework Reference Manual Index–9
wsetpkey command 1-446wsetpm command 1-447wsetpr command 1-448wsetquery command 1-450wsetrim command 1-452wsetrimpw command 1-454wsettap command 1-308, 1-455wsettask command 1-457wsetval command 1-459wsndnotif command 1-461wstarthttpd command 1-463wstartsched command 1-464wstophttpd command 1-465wsub command 1-466wsupport command 1-468wtailnotif command 1-471wtemp command 1-476wtimezone command 1-475wtrace command 1-483wtskabort command 1-473wuname command 1-488wunstmn command 1-492wunsub command 1-495wupdate command 1-497wvalidate command 1-499wxterm command 1-500
Index–10 Version 3.7