Centrify Suite

ADEdit Programmers Guide

November 2011

Centrify Corporation

Legal notice
This document and the software described in this document are furnished under and are subject to the terms of a license agreement or a non-disclosure agreement. Except as expressly set forth in such license agreement or non-disclosure agreement, Centrify Corporation provides this document and the software described in this document as is without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. Some states do not allow disclaimers of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This document and the software described in this document may not be lent, sold, or given away without the prior written permission of Centrify Corporation, except as otherwise permitted by law. Except as expressly set forth in such license agreement or non-disclosure agreement, no part of this document or the software described in this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, or otherwise, without the prior written consent of Centrify Corporation. Some companies, names, and data in this document are used for illustration purposes and may not represent real companies, individuals, or data. This document could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein. These changes may be incorporated in new editions of this document. Centrify Corporation may make improvements in or changes to the software described in this document at any time. 2004-2011 Centrify Corporation. All rights reserved. Portions of Centrify DirectControl are derived from third party or open source software. Copyright and legal notices for these sources are listed separately in the Acknowledgements.txt file included with the software. U.S. Government Restricted Rights: If the software and documentation are being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), in accordance with 48 C.F.R. 227.7202-4 (for Department of Defense (DOD) acquisitions) and 48 C.F.R. 2.101 and 12.212 (for non-DOD acquisitions), the governments rights in the software and documentation, including its rights to use, modify, reproduce, release, perform, display or disclose the software or documentation, will be subject in all respects to the commercial license rights and restrictions provided in the license agreement. Centrify, DirectAudit, DirectControl and DirectSecure are registered trademarks and DirectAuthorize and DirectManage are trademarks of Centrify Corporation in the United States and other countries. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. Centrify Suite is protected by U.S. Patents 8,024,360 and 7,591,005. The names of any other companies and products mentioned in this document may be the trademarks or registered trademarks of their respective owners. Unless otherwise noted, all of the names used as examples of companies, organizations, domain names, people and events herein are fictitious. No association with any real company, organization, domain name, person, or event is intended or should be inferred.

Contents
About this guide
9

Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Using this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Guide conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Using online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Where to go for more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Contacting Centrify Corporation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 1

Introduction

14

ADEdit features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 ADEdit in action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 2

ADEdit overview

17

ADEdits operating environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ADEdit components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 ADEdit context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 The ADEdit command set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 3

Getting started with ADEdit

24

ADEdit installation and use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Syntax and general operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Using ADEdit scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Typical ADEdit logic flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Selecting an object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Creating a new object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Examining objects and context. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Modifying or deleting selected objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Saving selected objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Pushing and popping context. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 4

ADEdit command reference

34

Command groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Command descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 add_command_to_role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 add_map_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 add_object_value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 add_pamapp_to_role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49 add_sd_ace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 create_computer_role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 create_zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 delegate_zone_right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 delete_dz_command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64 delete_map_entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65 delete_nis_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 delete_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 delete_pam_app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 delete_role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72 delete_role_assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 delete_sub_tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 delete_zone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77 delete_zone_computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79 delete_zone_group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 delete_zone_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82 dn_from_domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 dn_to_principal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84 domain_from_dn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85 explain_sd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86 get_adinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89 get_bind_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90 get_child_zones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92 get_dz_commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 get_dzc_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 get_group_members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

ADEdit Programmers Guide

get_nis_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 get_nis_map_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 get_nis_maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 get_object_field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 get_objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 get_pam_apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 get_pam_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 get_parent_dn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 get_pwnam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 get_rdn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 get_role_apps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 get_role_assignment_field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 get_role_assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 get_role_commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 get_role_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 get_roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 get_schema_guid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 get_zone_computer_field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 get_zone_computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 get_zone_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 get_zone_group_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 get_zone_groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 get_zone_nss_vars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 get_zone_user_field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 get_zone_users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 get_zones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 getent_passwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 joined_get_user_membership. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 joined_name_to_principal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 joined_user_in_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 list_dz_commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 list_nis_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 list_nis_maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Contents

list_pam_apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 list_role_assignments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 list_role_rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 list_roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 list_zone_computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 list_zone_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 list_zone_users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 new_dz_command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 new_nis_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 new_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 new_pam_app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 new_role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 new_role_assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 new_zone_computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 new_zone_group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 new_zone_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 pop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 principal_from_sid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 principal_to_dn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 quit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 remove_command_from_role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 remove_object_value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 remove_pamapp_from_role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 remove_sd_ace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 save_dz_command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 save_nis_map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 save_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 save_pam_app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 save_role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 save_role_assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 save_zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 save_zone_computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 save_zone_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

ADEdit Programmers Guide

save_zone_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 select_dz_command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 select_nis_map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 select_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 select_pam_app. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 select_role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 select_role_assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 select_zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 select_zone_computer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 select_zone_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 select_zone_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 set_dzc_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 set_ldap_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 set_object_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 set_pam_field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 set_role_assignment_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 set_role_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 set_sd_owner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 set_user_password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 set_zone_computer_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 set_zone_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 set_zone_group_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 set_zone_user_field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 sid_to_escaped_string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 sid_to_uid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 validate_license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Chapter 5

ade_lib Tcl library reference

282

Using the ade_lib Tcl library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Command synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Command descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 add_user_to_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 convert_msdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 create_adgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Contents

create_aduser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 create_assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 create_group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 create_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 explain_groupType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 explain_trustAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 explain_trustDirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 explain_userAccountControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 list_zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 modify_timebox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 precreate_computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 remove_user_from_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Appendix A

Timebox value format

308

Hex string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Hour mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Day mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Appendix B

ADEdit command abbreviations Index

311 315

ADEdit Programmers Guide

About this guide

Centrify ADEdit is a command-line interface (CLI) utility that runs on Linux and UNIX computers. Administrators can use ADEdit to manage Centrify DirectControl, Centrify DirectAuthorize, and Microsoft Active Directory. ADEdit offers every management feature available through the DirectControl console or any other DirectControl interface. It also adds some extra management features of its own. ADEdit is a Tcl (Tool control language) application that provides full scripting ability using Tcl. Administrators can write powerful and flexible DirectControl management scripts in Tcl that perform complex tasks with a single execution. Tcl programmers can include ADEdit in Tcl applications to add full DirectControl management to those applications, and to build their own GUI interfaces for ADEdit if desired.

Intended audience
This guide describes ADEdit for network administrators who want to manage DirectControl, DirectAuthorize, and Active Directory on a Linux, UNIX, or Mac platform through CLI commands or scripts. It assumes that you are well-versed in Active Directorys architecture and management, and that youre equally well-versed in DirectControl and DirectAuthorize. ADEdit is a powerful tool that can make significant changes to Active Directory and DirectControl (based on your accounts access rights), including completely erasing all objects in Active Directory with no chance to undo your actions. Its important that if you use ADEdit with full rights that you know exactly what youre doing. Its useful to know Tcl if you intend to write scripts using ADEdit commands, but not necessary if you use ADEdit in interactive mode to enter a command at a time through a shell. This book explains a few DirectControl concepts as they arise, but for full information about DirectControls architecture and management, you should read the Administrators Guide. For a comprehensive explanation of Tcl and its use, we recommend Tcl and the Tk Toolkit by John K. Ousterhout and Ken Jones (published by Addison-Wesley).

Using this guide

This guide presents ADEdit conceptual information up front, followed by instructions for using ADEdit. Chapters at the back provide full reference material for each ADEdit command and each procedure in the accompanying ade_lib Tcl library. We recommend that you read the conceptual and introductory material before using ADEdit for the first time. Youll find the command reference useful later as you start using ADEdit in everyday work.

Guide conventions

This is a short description of each chapter in this book: Chapter 1, Introduction, describes ADEdit, problems its meant to solve, features it offers, and its typical uses.

Chapter 2, ADEdit overview, describes the environment in which ADEdit operates: typical network components, Active Directory, and other DirectControl management tools. It also discusses ADEdits components, its stateful nature, and the types of commands it offers. Chapter 3, Getting started with ADEdit, describes ADEdit and its general operation: standard command syntax, using scripts, binding to domains, selecting objects to work on them, saving objects, working with contexts, and so on. Chapter 4, ADEdit command reference, is a detailed description of each ADEdit command listed in alphabetical order for easy access. Chapter 5, ade_lib Tcl library reference, describes each utility command available in the ade_lib Tcl library. Appendix A, Timebox value format, describes the format of the timebox value used to set hours of the week when a role is enabled and disabled. Appendix B, ADEdit command abbreviations, lists all the ADEdit command abbreviations in alphabetical order, useful for interpreting scripts that used abbreviations instead of full commands.

An index at the back of the guide provides quick look-up of topics in the guide.

Guide conventions
We use the following conventions in this guide: Fixed-width font presents sample code, program names or output, file names, and commands that you type at the command line. When italicized, the fixed-width font indicates variables.

Bold text emphasizes commands, buttons, or user interface text, and introduces new terms. Italics present book titles and emphasize specific words or terms. Terms enclosed in [braces] in command syntax are optional.

Using online help

ADEdit provides help text for each of its commands: simply enter help <command_name> when running ADEdit to see the help text for a command. The reference description of help on page 152 provides more details.

ADEdit Programmers Guide

10

Where to go for more information

You can display general help text for ADEdit by entering man

adedit

in a shell.

All Centrify Suite documentation, including this guide, is available in searchable Acrobat PDF files.

Where to go for more information

The basic Centrify Suite documentation set includes multiple sources of information: Release Notes included on the distribution media or in the download package provide the most up-to-date information about the current release, including system requirements and supported platforms, and any additional information specific to this release that may not be included in other documentation.

Quick Start for UNIX Services provides a brief summary of the steps for installing Centrify DirectControl and getting started so you can begin working with the product right away. For more detailed information about installing Centrify DirectControl, see the Planning and Deployment Guide. Evaluation Guide provides information to help you set up an evaluation environment and use Centrify DirectControl to test typical authentication and authorization scenarios, such as resetting user passwords for UNIX computers, preventing a user from accessing unauthorized UNIX computers, preventing a user from accessing unauthorized UNIX computers, or enforcing specific lockout policies when users attempt to log on to UNIX computers using Centrify DirectControl. Planning and Deployment Guide provides guidelines, strategies, and best practices to help you plan for and deploy Centrify DirectControl in a production environment.This guide covers issues you should consider in planning a Centrify DirectControl deployment project. The Planning and Deployment Guide should be used in conjunction with the information covered in the Administrators Guide. Administrators Guide describes how to perform administrative tasks using the Centrify DirectControl Administrator Console and UNIX command line programs. The Administrators Guide focuses on managing your environment after deployment. Web Console Users Guide describes how to perform administrative tasks for zones using the Centrify DirectControl Web Console. The DirectControl Web Console enables you to perform a subset of DirectControl tasks by connecting to a Web server from computers that do not have the Administrator Console installed. Group Policy Guide describes the Centrify DirectControl group policies you can use to customize user-based and computer-based configuration settings. This guide provides an overview of how group policies are applied and how to install and enable DirectControlspecific policies.

About this guide

11

Contacting Centrify Corporation

Configuration Parameters Reference Guide provides reference information for the configuration parameters that enable you to customize your environment. Many of these settings can also be controlled through group policies. Administrators Guide for Mac OS X provides information for Mac OS X system administrators about the administrative issues and tasks that are specific or unique to a Mac OS X environment. If you are deploying in an environment with Mac OS X servers or workstations, you should refer to this guide for information about the group policies that only apply to Mac OS X computers and users. NIS Administrators Guide provides information about installing and configuring the Centrify DirectControl Network Information Service (adnisd) and NIS clients to incorporate NIS maps into an Active Directory environment. If you are planning to use both the Centrify DirectControl Agent and Centrify DirectControl Network Information Service to support NIS clients, you should refer to this guide for information about how to import and manage NIS maps in Active Directory. Authentication Guide for Apache describes how to use Centrify DirectControl with Apache servers and applications to provide authentication and authorization services through Active Directory. If you are using Centrify DirectControl with Apache, you should refer to this supplemental documentation for details about how to configure your Apache server to use Centrify DirectControl and Active Directory. Authentication Guide for Java Applications describes how to use Centrify DirectControl with J2EE applications to provide authentication and authorization services through Active Directory. If you are using Centrify DirectControl with Java servlets, such as Tomcat, JBoss, WebLogic, or WebSphere, you should refer to this supplemental documentation for details about how to configure your applications to use Centrify DirectControl and Active Directory. DirectAudit Administrator Guide describes how to install and configure DirectAudit, monitor the system with the Administration Console, and query and play back audited data with the Auditor Console. Individual UNIX man pages for command reference information for Centrify DirectControl UNIX command line programs.

In addition to the Centrify Suite documentation, you may want to consult the documentation for your Windows or UNIX operating system, or other application- or system-specific documentation for reference and conceptual information. This background information can help you get the most out of your Centrify Suite installation.

Contacting Centrify Corporation

If you have questions or comments, we look forward to hearing from you. For information about contacting Centrify Corporation with questions or suggestions, visit our Web site at

ADEdit Programmers Guide

12

Contacting Centrify Corporation

www.centrify.com. From the Web site you can get the latest news and information about products, support, services, upcoming events, investor relations, and sales. For information about purchasing or evaluating Centrify products, send email to [email protected].

About this guide

13

Chapter 1

Introduction
ADEdit is a valuable tool for administrators working on a Linux or UNIX platform who want to manage DirectControl through CLI commands or through script execution. ADEdit supersedes some of Centrifys previous-generation UNIX tools including adupdate and adquery. It expands control beyond the host machines currently joined zone and domain, and manages many more DirectControl features than its predecessors. This chapter introduces you to ADEdits main features and shows you examples of use. Youll find a more detailed description of ADEdits command set and architecture in the next chapter, ADEdit overview.

ADEdit features
ADEdit provides an extensive administrative scope, offers multiple modes of execution, and provides an accompanying library of utility scripts.

Administration scope
ADEdit offers complete control of DirectControl (DC) and DirectAuthorize (DZ) from a single UNIX location. It controls every aspect of operation that the DirectControl console offers and provides additional capabilities as well; a knowledgable DC administrator can use ADEdit alone for complete DC administration. You may find the DirectControl console in Windows easier to use for some tasks, howeverits graphical user interface is more intuitive and it walks users through some procedures. The console also fills in default field values in many cases such as creating new objects where ADEdit does exactly what its requested to do and fills in only provided field values. ADEdit can operate on any domain in any forest. Its host computer does not need to be joined to a domain for ADEdit to work with that domain. As long as the administrator has the necessary authentication and rights to work on a domain, ADEdit can bind to the domain and work on it. ADEdit can work simultaneously on multiple domains in multiple forests. ADEdit includes the features of multiple tools, offering them all within a single CLI tool. It replaces adupdate and adquery and offers the features of LDAP clients such as ldapsearch.

Execution
ADEdit offers multiple methods of execution:

14

ADEdit in action

Interactive mode. In interactive mode, ADEdit executes single CLI commands in real time. You can enter a series of commands within a shell to perform simple administrative tasks. ADEdit offers command history that is persistent from session to session. You can use the up arrow and Enter keys to review and re-enter commands instead of retyping complete commands from scratch. Script execution. ADEdit can accept and execute a Tcl script file that includes ADEdit commands (an ADEdit script). The Tcl scripting language includes full programming logic with variables, logical operators, branching, functions (called procedures in Tcl), and other useful program-flow features. As the script executes, ADEdit saves time and computing resources by keeping AD objects that its working on in internal memory. It doesnt require repeated queries to AD as it works on an object. Executable file. You can set up any ADEdit Tcl script as an executable file that can run by itself on a UNIX platform.

The ade_lib Tcl library

ADEdit installs with an accompanying library of utility procedures called the ade_lib Tcl library. These procedures use ADEdit commands to perform standard administrative operations such as adding zone users to a zone group or creating a new AD user. They also provide examples of how to use ADEdit commands efficiently in Tcl scripts.

ADEdit in action
Part of ADEdits utility is the ability to fully manage DirectControl and DirectAuthorize from a UNIX platform. An administrator working on a users Linux machine to help the user set up accounts can, for example, run ADEdit to create a new zone user account, assign the user to different groups, assign roles to the user, and fill in user account information. He can also query Active Directory for information about zones, groups, roles, and any other DirectControl objects and can evenif desiredcreate any of those DC objects, modify existing objects, or delete objects. The administrator can perform any action through ADEDit that he can through the DC console. Scripting makes ADEdit a very powerful administration tool. A well-written script can handle hundreds or thousands of repetitive tasks that would take a very long time to perform through the console, and can check on and respond to current conditions to ensure that it carries out the proper activities. A script could, for example, create a new zone, read etc/passwd files on UNIX machines in that zone, and migrate all existing UNIX users it finds there into new zone user accounts. Another script could find users in specified groups and then assign a new role to all users in those groups. ADEdit scripts are limited mainly by the imagination and skill of the programmer. With that power comes responsibility. Its quite possible for an ADEdit scriptor even a single ADEdit commandto completely erase Active Directorys contents if used

Chapter 1 Introduction

15

ADEdit in action

incorrectly (and with the necessary permissions). There are, for the most part, no warnings and there is no undo feature if this happens. Only knowledgeable users should use ADEdit, and its important to test scripts in sample environments before deploying them in the real world.

ADEdit Programmers Guide

16

Chapter 2

ADEdit overview
This chapter looks at the components ADEdit works with in its operating environment and examines other DirectControl management tools that ADEdit may work alongside. The chapter then explores ADEdits architecture: its components, the context it maintains, and its command set.

ADEdits operating environment

This is a very simplified description of Centrifys DirectControl environment in combined Windows and UNIX networks. Its here to point out what components ADEdit works with. Youll find a far more detailed description of the entire DirectControl environment in the Administrators Guide.

Windows network
ADEdits primary partner is Active Directory (AD), which runs in a Windows network. AD contains not only standard forest and domain data, but also stores DirectControlspecific data such as zone information. Active Directory uses multi-master data store. It replicates directory data on multiple domain controllers throughout a domain. Changes in data on one domain controller are replicated to the other domain controllers in the domain. ADEdit binds to one or more Active Directory domain controllers. ADEdit can query AD for data within bound domains, retrieve AD objects, modify those objects, create new objects, and delete existing objects. Those objects include all DirectControl-specific objects such as zone objects, zone user objects, role objects, and more.

UNIX network
Computers within a UNIX network use installed DirectControl components to integrate themselves into an Active-Directory-controlled zone. ADEdit works directly with some of these components: adclient is a Centrify process running on a UNIX computer. adclient communicates with AD to integrate its host computer with the network under DirectControl. adclient can query AD for DirectControl-supplied authentication and authorization data. adclient also supplies hooks for standard UNIX authentication and authorization mechanisms on the host computer such as PAM that contact adclient for authentication and authorization through AD.

17

ADEdit components

ADEdit typically contacts AD directly and doesnt work through adclient, but has a few commands that work through adclient to get information thats more efficient to retrieve through adclient than from AD directly.

Centrify CLI commands, a set of commands that control adclient and work with DirectControl data stored in AD. ADEdit replaces some of these commands, but occasionally works in conjunction with other commands such as adflush, especially when executing ADEdit commands that work through adclient.

Other DirectControl administration tools

You have two other administrative options in addition ADEdit: The DirectControl console runs on a Windows computer and provides a graphical user interface that you can use for complete control of DirectControl, the DC objects it manages, and some AD features. This is the traditional DC administration tool.

The DirectControl API, when incorporated into a custom Windows application, can control all the DC, DZ, and AC features that the DC console does, but from within the application.

Its important to realize when using any of these tools that an instance of one of these tools has no knowledge of other tool instances and acts as if its the only DirectControl administration tool at work. For example, if one administrator works with the DirectControl console to modify a zone object at the same time as another administrator uses ADEdit to modify the same zone object, they may clash with each other: changes first saved by the DirectControl console may be overridden by changes saved by ADEdit. The last tool to save object data has the final say. This is true as well for different instances of ADEdit. If two administrators both use different ADEdit instances simultaneously to work on the same object, the administrator who last saves the object is the only one whose work will have an effect on the object. Its important when using ADEdit in an environment with multiple administrators to retrieve an object, make changes, and check it back in efficiently to avoid conflicts. ADEdit object changes are not atomic. It helps to bind all DirectControl administration tools to the same domain controller within a domain to further minimize conflicts. If tools work on different domain controllers, one tools changes may take time to replicate to the other domain controllers, so other tools connected to other domain controllers wont be able to see those changes immediately.

ADEdit components
ADEdit has two components: the ADEdit application and the ade_lib Tcl library. Theyre both installed on a UNIX platform during DirectControl installation. (Installation includes adclient).

ADEdit Prograrmmers Guide

18

ADEdit components

U se r

T cl S crip ts

CLI

T cl Interpeter A D E dit C om m ands T cl C om m ands

ad e_lib T cl library

A D E dit
A ctive D irectory D om ain C ontroller

U N IX /Linux/M ac com puter

adclient

Figure 1. A user can access ADEdit through a CLI (a shell) or through an executing Tcl script or application. ADEdits Tcl interpreter executes commands it receives from the CLI using the ADEdit commands and Tcl commands that are part of ADEdit. It may also use ade_lib Tcl library commands if specified. Tcl scripts and applications use ADEdits commands and ade_lib Tcl library commands directly. ADEdit binds to an Active Directory domain controller, with which it exchanges data. ADEdit may also (in a few cases) get data from Active Directory through the adclient process.

The ADEdit application

ADEdit uses Tcl as its scripting language. Tcl is a long-established extensible scripting language that offers standard programming features and an extension named Tk that creates GUIs simply and quickly. Tcl is described in the authoritative book Tcl and the Tk Toolkit by John K. Ousterhout and Ken Jones (Addison-Wesley, 2010). ADEdit includes a Tcl interpreter and the Tcl core commands, which allow it to execute standard Tcl scripts. ADEdit also includes a set of more than 120 of its own commands designed to manage DirectControl, DirectAuthorize, and Active Directory. ADEdit will execute individual commands in a CLI (in interactive mode) or sets of commands as an ADEdit script.

The ade_lib Tcl library

The ade_lib Tcl library is a collection of Tcl procedures that provide helper functions for common DC management tasks such as listing zone information for a domain or creating an AD user. You can include ade_lib in other ADEdit scripts to use its commands.

Chapter 2 ADEdit overview

19

ADEdit context

ADEdit context
When ADEdit commands work on AD objects, they dont specify a domain and the object to work on as part of each command. ADEdit instead maintains a context in memory that defines what commands work on. ADEdits context has two types of components: A set of one or more bindings that connect ADEdit to domains in the forest. Each binding uses an authentication to connect to an AD domain controller. The authentication must have enough rights to perform ADEdits administrative actions on the domain controller. Each binding binds ADEdit to a single domain; multiple bindings bind ADEdit to multiple domains at one time.

A set of zero, one, or more selected AD objects that ADEdit works on. A selected object is typically a DC or DZ object such as a zone, zone user, role, or NIS map, but may also be any generic AD object. ADEdit stores each selected object with all of its attributes (called fields within ADEdit). ADEdit stores no more than one type of each selected object: one zone object, for example, one PAM application object, one generic AD object, and so on.

An ADEdit session or script typically starts by binding to one or more domains. If ADEdit isnt bound to a domain, none of its commands that work with Active Directory (which is most of them) have any effect. Once bound, ADEdit commands work within the scope of all currently bound domains. An ADEdit session or script then typically selects an object to work on: it specifies an object such as a zone user object that ADEdit retrieves from AD and stores in memory as part of the context. All subsequent zone user commands then work on the zone user object in memory, not the zone user object as it is stored in AD. When finished with a selected object, the session or script can simply ignore the object (if nothing has changed in it) or it can save the object back to AD (if the object has been modified and modifications need to go back to AD, overwriting the object there). The selected object remains stored in ADEdits context until the session or script selects a new object of the same type, which replaces the previous object. By maintaining a context with selected objects, ADEdit avoids constant AD queries for successive object management commands: A selection command queries AD to retrieve an object. Reading or modifying object fields occurs internally and doesnt require AD queries. If the object is saved, a final AD query returns the modified object to AD.

Context persistence
ADEdits context persists for the duration of an ADEdit interactive session. The context in an ADEdit script persists only until the end of the scripts execution.

ADEdit Prograrmmers Guide

20

The ADEdit command set

Pushing and popping contexts

ADEdit can save and retrieve contexts using push and pop commands that use a stack to store successive levels of context. Pushing and popping contexts is useful within Tcl scripts when jumping to a procedure. The script can push the current context to the stack, create an entirely new context for the procedure, then pop the original context back when exiting the procedure.

Context cautions
Working with ADEdits context requires some thought. Commands that affect objects dont explicitly specify an object, so you must be careful to ensure that the correct object is specified before executing commands that affect the object. ADEdit has context reporting commands that help by showing current domain bindings and selected objects. Its important to realize that any modifications to a selected object have no effect until the object is saved back to AD. If you forget to save an object, you lose all modifications. If you keep an object in context a long time between selecting the object and saving the object, be awareas noted earlierthat another administration tool may alter the object in AD during that time and you wont know about those alterations.

The ADEdit command set

ADEdit offers a set of over 120 commands. Chapter 4, ADEdit command reference, provides a detailed description of each of ADEdits commands. This section describes the commands in general to give you an idea of what ADEdit can do.

General-purpose commands
ADEdits general-purpose commands control ADEdits overall operation and provide information about ADEdit: they provide help text for commands, set the LDAP query time-out interval, set up caching for queries, and quit ADEdit.

Context commands
Context commands set up and control ADEdits context. They bind to domains, report current bindings, show current bindings and selected objects, and push and pop contexts off ADEdits context stack.

Object-management commands
Object management commands are the core of ADEdit. They retrieve, read, manipulate, save, and delete AD objects. Theres a set of object-management commands for each type of object you can select in ADEdits context:

Chapter 2 ADEdit overview

21

The ADEdit command set

Zones (which include computer roles, considered a type of zone) Zone users Zone groups Zone computers Roles Role assignments PAM (Pluggable Authentication Module) applications DirectAuthorize (DZ) commands NIS (Network Information Service) maps Generic AD objects (which can be any object type)

Each object types command set is similar to command sets for other object types (with a few exceptions). An object types command set typically contain these commands: A get_<object> command (get_zone_users, for example) returns a Tcl list of the objects of this type that are stored in AD for the currently selected zone (or, in the case of get_zones, for the currently bound domains). A script can use the Tcl list to act on returned dataeach listed object is a key that the script can use to retrieve the object.

A list_<object> command (list_zone_groups, for example) returns a list to stdout of the objects of this type that are stored in AD for the currently selected zone. Each object listed is accompanied by at least some of the objects attribute data. Because the list goes to stdout, this command type is useful to display data for interactive use as a script executes. A new_<object> command (new_zone_user, for example) creates a new object of the specified type and stores it in ADEdits context as the currently selected object of that type. The command does not store the new object in AD. A create_<object> command (create_zone, for example) creates a new object of the specified type and writes it to AD, but does not put a copy in the ADEdit context. This means the newly created object is not selected after its created. A select_<object> command (select_nis_map, for example) retrieves the specified object from AD and stores it in ADEdits context as the currently selected object of that type. The newly selected object replaces the previously selected object of that type if one exists. Selecting an object retrieves and stores all of the objects attributes with the object andif it replaces a previous objectdoes not save the previous object to AD. A get_<object>_field command (get_zone_group_field, for example) returns the value of a specified field (attribute) from the currently selected object of that type stored in ADEdit. It does not get the attribute value from AD. A set_<object>_field command (set_zone_computer_field, for example) sets the value of a specified field (attribute) in the currently selected object of that type. It does

ADEdit Prograrmmers Guide

22

The ADEdit command set

not change the attribute value in AD and wont have any effect until the object is saved to AD.

A save_<object> command (save_dz_command, for example) saves the currently selected object of that type to AD. If you dont save an object that has been modified, none of the modifications are saved. And if you dont save an object created by a new_<object> command, the new object disappears as soon as another object of that type is selected or when ADEdit quits. A delete_<object> command (delete_zone_user, for example) deletes the currently selected object of that type from memory and deletes the same object from AD.

Some object types have a few additional object-management commands that handle special features of that object type. There is also some variation in the way these command types work when handling generic AD objects. It pays to check the detailed command descriptions before using the commands.

Utility commands
Utility commands perform useful data retrieval and data conversion tasks. They convert domain names and security principal names from format to format and they manipulate distinguished names (DNs). They check with AD to convert between user principal names (UPNs) and distinguished names. They query AD for local users, look up users by UNIX name, look up security principals by security IDs (SIDs), and convert SIDs to escaped strings. They also return information about users, groups, and group membership and set user passwords.

Security descriptor commands

Security descriptor (SD) commands modify security descriptors and make them readable by humans.

Chapter 2 ADEdit overview

23

Chapter 3

Getting started with ADEdit

This chapter describes ADEdits basic syntax, shows the typical logic flow used to handle DirectControl objects, and describes in detail the steps in that logic flow. It provides simple examples.

ADEdit installation and use

Standard DirectControl installation on a UNIX, Linux, or Macintosh computer installs ADEdit and its accompanying library ade_lib along with adclient and other standard DirectControl components. Both ADEdit and ade_lib should be available on any DirectControl-enabled UNIX, Linux, or Macintosh computer. You can execute ADEdit for an interactive session by entering adedit in a standard shell. Although anyone can execute ADEdit, it will have no effect on DirectControl or Active Directory unless the user provides authorization with the necessary rights to work with Active Directory.

Syntax and general operation

ADEdit includes a Tcl interpreter and uses Tcl syntax. The ADEdit commands have their own syntax within Tcl syntax, described in detail for each command in Chapter 4, ADEdit command reference.

Basic command syntax

Like other Tcl commands, ADEdit commands are case-sensitive. Theyre completely in lower case, so ADEdit wont recognize ADEdit commands with upper-case characters. An ADEdit command works very much like a UNIX command. An ADEdit command may or may not have arguments. Each argument is typically a variable that follows the command and provides data that the operation work on. Some variables may be required for a commands execution; others may be optional. Arguments must be entered in the order specified for the command. An ADEdit command may or may not have options. Each option is a single word preceded by a dash (-) such as -write. An option may have its own argument, which must immediately follow the option. An option controls the operation of the ADEdit command. Options must precede a commands arguments. As an example:
>bind -gc acme.com administrator #3gEgh^&4

24

Syntax and general operation

In this example, the bind command has an option -gc that specifies a global catalog domain controller. Three arguments follow the option. The first argument is required and specifies the domain to which to bind. The second and third arguments are optional and provide a log-in name and password used for binding.
Note The > preceding the bind command is the prompt you see in an interactive ADEdit session after starting the session by entering adedit in a standard shell. Youll see it in later examples that assume were entering commands in an interactive ADEdit session.

Results
When an ADEdit command successfully executes, it produces no output or return (similar to UNIX commands) unless its defined to return a result. If the command fails, ADEdit notifies you of an error in execution and reports the general reason for failure: a wrong number of arguments, for example, or connection problems and so on. Commands that return results may return a Tcl list that other commands in a Tcl script may work with, or they may output results to stdout where its displayed in the shell to the user. The user can redirect the commands stdout output to a file or other destination if desired. Commands that return Tcl lists start with get_; commands that output to stdout start with list_.

Abbreviations
Most ADEdit commands have equivalent abbreviations that you can use in place of the fulllength commands. list_zone_users, for example, has the abbreviation lszu. You can use either the full command name or the abbreviation with the same effect. Abbreviations are useful in interactive sessions to reduce the amount of typing you have to do. You can also use them in scripts, but theyll make the code harder to read for people who dont know the abbreviations by heart. If you need to look up an abbreviation, youll find a complete list in alphabetical order in Appendix B, ADEdit command abbreviations.

Command history
ADEdit in an interactive session retains a history of previously entered commands. You can visit the command history by pressing the up arrow key to go back in the history and the down arrow key to forward. Pressing Enter when displaying a previously entered command re-enters that command entry, very convenient when its necessary to repeat a command. ADEdit retains its command history across sessions, so if you quit ADEdit and restart it, you can still visit commands entered in the previous session. The command history has a 50command capacity. Once full, the history drops old commands as new commands enter.

Chapter 3 Getting started with ADEdit

25

Using ADEdit scripts

The help command

ADEdits help command provides information about ADEdit commands. If you enter help in ADEdit followed by a command or command abbreviation, help returns information about that command, including its syntax. You can use the wildcard characters * (specifying any number of variable characters) or ? (specifying a single variable character) within a command string following help. help will return help text for all commands that match the wildcard string.
> help get*

for example returns help for all commands that start with get.

Using ADEdit scripts

You can use ADEdit in scripts in two ways: You can execute an ADEdit script using ADEdit directly.

You can set up an ADEdit script as an executable file to execute from outside of ADEdit.

Executing an ADEdit script using ADEdit

To execute an ADEdit script using ADEdit, in a shell enter adedit followed by the name of the script (using a path if the script isnt in the current directory) and arguments if the script requires any. For example:
adedit zonemgr

executes the ADEdit script zonemgr.

Setting up an ADEdit script as an executable file

To set an ADEdit script as a UNIX-executable file:
1 Put #!
/usr/bin/adedit as the first line of your ADEdit script. The script reads it as a comment, but UNIX will use it to find and execute ADEdit and then use it to execute the rest of the script. +x yourfile,

2 Use chmod to make the file executable in UNIX (chmod

for example).

3 Make sure the files directory is listed in your PATH environment variable if you want to

be able to execute the file from any directory. Once set up this way, you should be able to simply enter the scripts filename in a shell and have the script execute as a command.

Typical ADEdit logic flow

Using ADEdit to manage DirectControl and Active Directory has a typical logic flow:

ADEdit Prograrmmers Guide

26

Binding

Binding. You bind ADEdit to one or more domains within a forest. Binding specifies the arena within which all subsequent commands work. Selecting or creating an object. You either select an existing Active Directory object or you create a new Active Directory object. Selection retrieves an object from Active Directory and stores it in memory. Creating a new object puts the new object in memory. Reading or modifying a selected object. Once an object is selected, you can read its field values to see its current state. You can also write new field values to the object to change its state. Reading or writing takes place only on the object in memory, not the object as its stored in Active Directory. Saving a selected object. If you modify an object in memory or youve created a new object there, you must save it back to Active Directory to have any effect.

ADEdit is very stateful. The bindings you set and the objects you select determine ADEdits current stateits context. All commands work within that context. If you select a zone user, for example, you may only select zone users from within ADEdits bound domains. And if you select a zone, subsequent commands assume that your selected zone is the zone in which to add new zone users, zone computers, and zone groups.

Binding
ADEdit must bind to one or more domains before any commands that depend on Active Directory will work. The bind command binds ADEdit to a domain. It specifies the domain to which to bind and may optionally provide authentication (user and password) for the binding.

Domain and domain controller

You must specify a domain when using bind. The domain can be any domain in the current forest. ADEdits host machine doesnt have to be joined to a domain to bind to and work with a domain. A binding command can be as simple as:
>bind acme.com

If you specify a domain for binding with no options set, ADEdit automatically finds the closest, fastest domain controller in the domain for the binding. Options can narrow down the choice. The -write option specifies that auto-selection chooses a writable domain controller; the -gc option specifies that auto-selection chooses a general catalog (GC) domain controller. You may use both options to choose a writable GC domain controller for example:
>bind -write -gc acme.com

If you know the server of a specific domain controller to which youd like to bind, you may specify it preceding the domain:
>bind [email protected]

Chapter 3 Getting started with ADEdit

27

Binding

Keep in mind that Active Directory is a multi-master LDAP system. Changes made at any one domain controller eventually propagate to all other domain controllers in the domain (if theyre universal changes). If all DirectControl administration tools (the console, for example, or other instances of ADEdit) bind to the same domain controller, then changes that any one of the tools makes are immediately available to the other tools without waiting for propagation.

Authentication
If no authentication is provided with a bind command, as in the previous examples, ADEdit gets its authentication data from the Kerberos credentials cache if one exists. You can provide a user name if youd like, in which case bind prompts for a password, or you can provide both user name and password:
>bind acme.com administrator {e$t86&CG}

Notice that the password is enclosed in braces ({}) to ensure that Tcl handles it correctly. Tcl syntax will automatically substitute for some characters such as the $ used in the password. (A dollar sign specifies the contents of a variable in Tcl.) Such substitutions alter text so that a password, for example, might not work. Enclosing a string in braces guarantees that Tcl will not try to substitute for any of the characters in the string. Tcl drops the braces when it passes the string on. You may also use the credentials of ADEdits host machine if youd like by using the machine option:
>bind -machine acme.com

Note that whatever credentials you use, they must be for an account with enough authority to read from and make changes to Active Directory objects in the domain. Without the proper authority, ADEdit commands that use Active Directory wont work.

Binding scope and persistence

Binding to a single domain allows ADEdit commands to work on Active Directory in that domain. You can bind to multiple domains if you like; that expands the scope of ADEdit to work on more than one domain. To do so, you simply use multiple bind commands, one for each domain you want. Once bound to a domain, ADEdit remains bound to that domain until another binding occurs to the same domain (possibly using a different authentication or specifying a different domain controller) or until the current interactive session or executing script ends. Binding may also end if the current context is popped and ADEdit reverts to an earlier context without the binding. (We describe pushing and popping later in the chapter.)

ADEdit Prograrmmers Guide

28

Selecting an object

Binding and join differences

Its important to realize that an ADEdit binding is not the same as the host computers join. A join is the adclient processs connection to Active Directory for the host computer, and is not ADEdits connection. A join may be to a single domain only. A binding is ADEdits connection to Active Directory, may be to one or more domains in the forest, including those not joined, and is completely independent of the host machines joined domain. That said, a few ADEdit commands go through adclient to retrieve data from Active Directory and so are affected by the host machines join state. They can only get data from the joined domain. These commands names start with joined_ so theyre easy to recognize.

Controlling binding operation

You can control the way ADEdits binding to Active Directory operates. The set_ldap_timeout command sets a time interval for ADEdits LDAP queries to execute by Active Directory. ADEdit considers a query that doesnt execute by the time-out interval as failed.

Selecting an object
ADEdit manages DirectControl by working with the objects in Active Directory that create and define DirectControl entities. Those objects types are: Zones

Zone users Zone computers Zone groups Roles Role assignments DirectAuthorize (DZ) commands PAM applications NIS maps Generic AD objects

Selection commands
ADEdit has a set of object selection commands in the form select_xxx where xxx is an object type. When you select an object with one of these commands (select_zone, for example), ADEdit looks for the object in Active Directory and retrieves it to store the

Chapter 3 Getting started with ADEdit

29

Creating a new object

object in memory (the current context). Each select command is tailored to the type of object it retrieves. As an example, after binding to acme.com we query to see what zones exist in a domain and then select one of the zones using select_zone. Each zone is specified by its distinguished name (DN):
>get_zones acme.com {CN=default,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} {CN=cz1,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} {CN=cz2,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} {CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} >select_zone {CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com}

Selection as part of context

Once an object is selected, it resides in memory (context) with all attendant field values. Further ADEdit commands can examine and modify the object in context. By keeping an object in memory, ADEdit doesnt need to retrieve the object from Active Directory each time it needs to look at or work on the object, saving a lot of query time. ADEdit keeps only one selected object of each type in its context. If you select or create another object of the same type, the new object replaces the old object in memory without saving the old object to AD. ADEdit can and does keep multiple objects in context, but each object is of a different type. Note that currently selected objects often affect work on other objects types, especially the currently selected zone. If you select a zone user, for example, you must first select a zone so that ADEdit knows in which zone to look for the zone user. If you dont first select a zone, you cant select and work on various zone objects such as zone users, zone computers, and zone groups. Knowing your context as you work on objects is important.

Persistence
A selected object stays selected until another object of the same type replaces it or until the current interactive session ends or executing script ends. At that time, all selected objects disappear from ADEdits memory.

Creating a new object

ADEdit can create new objects to work on instead of selecting existing objects. A set of new_xxx commands, where xxx is the object type, creates objects. When you use one of these commands, ADEdit creates an object of the specified type and stores the object as the currently selected object of that type in ADEdits current context. The new objects fields are empty. You may fill them in with values by using other ADEdit commands described later. Note that ADEdit does not fill in default values for a new objects

ADEdit Prograrmmers Guide

30

Examining objects and context

fields the way the DirectControl console does. It does strictly what its asked to do and no more. An example of creating a new object:
new_zone_user [email protected]

In this example, new_zone_user finds the AD user [email protected] in Active Directory for the currently bound domains, then (if found) creates a new zone user of that name in the currently selected zone (global, as selected in the last example). ADEdit selects the new zone user, which places it in ADEdits context and replaces the previously selected zone user if one exists. Note that the new zone user does not yet exist in Active Directory and wont unless and until it is saved. If you quit ADEdit or finish an ADEdit script or select another object of the same type without saving the new object, it will vanish with no effect.

Creating a new zone

Creating a new zone works differently than all other object types: ADEdit does not create a new zone in memory, it creates a new zone directly in Active Directory. It does not select the new zone and store it in memory. Once created, you must select the zone to examine and modify it using ADEdit. Two commands create new zones: create_zone and create_computer_role. Unlike the other creating commands, they start with create_ instead of new_ so theyre easily distinguished from commands that create new objects in memory instead of directly in Active Directory. (Dont be confused by the term computer role in the command. A computer role, despite its name, is actually a type of zone as handled by ADEdit.)

Examining objects and context

ADEdits context is a combination of ADEdits current bindings and its currently selected objects. You can examine the properties of currently selected objects; you can also look at ADEdits current context at any time.

Getting object field values

ADEdit offers a set of commands in the form get_xxx_field, where xxx is an object type, that returns the value stored in a field of the currently selected object of that type. For example:
>get_zone_user_field uname adam

In this example, ADEdit retrieves the field uname (user name) for the currently selected zone user [email protected].

Chapter 3 Getting started with ADEdit

31

Modifying or deleting selected objects

Getting current context information

You can examine ADEdits current context at any time using two different commands. The show command by itself returns all bindings and selected objects in the current context:
>show Bindings: acme.com: calla.acme.com Current zone: CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com Current nss user: [email protected]:adam:10001:10001:%{u:samaccountname}:%{home}/ %{user}:%{shell}:

You can, using optional arguments, restrict show to return only the bindings, only the selected zone, only the selected role, and so on. The get_bind_info command returns detailed information about a bound domain. It may return the domains forest, the name of the currently bound server, the domains security identifier (SID), the functional level of the domain, or the functional level of the domains forest. For example:
>get_bind_info acme.com server adserve02.acme.com

In this example, its asked to return the bound server to it returns a server name.

Modifying or deleting selected objects

Once an object is selected and residing in ADEdits context, you modify it using any of ADEdits set_xxx_field commands where xxx is the object type. A set-field command takes a field name and a value and sets the field to the supplied value. For example:
>set_zone_user_field uname buzz

This sets the currently selected zone users user name to buzz. (The currently selected zone user as selected in a previous example is [email protected].) The field is set to a new value only in memory. You must save the object before the new field value is stored in Active Directory and takes effect within the objects domain.

Deleting an object
To delete a currently selected object, use a delete_xxx command where xxx is the object type. This command deletes the object from both memory and Active Directory. For example:
>delete_zone_user

deletes the currently selected zone user, [email protected] from ADEdits context so theres no longer a selected zone user and also deletes the zone user object [email protected] so theres no longer a zone user by that name in AD.

ADEdit Prograrmmers Guide

32

Saving selected objects

Note

There is no undo for a delete command. Once the object is deleted from AD, you must recreate it from scratch if you want it back. Be especially careful if you set up an ADEdit script to delete multiple objects.

Saving selected objects

Any new or modified object in ADEdits context has no effect until you save the object back to Active Directory. You do so using a save_xxx command where xxx is the object type. For example:
>save_zone

saves the currently selected zone object back to Active Directory along with any field values that have been modified since the zone was selected. Saving an object does not deselect the object; it remains the selected object in memory so that you can further read and modify it.

Pushing and popping context

There are times when you may want to save ADEdits current context, change it to a new context to work on different objects in different domains, and then revert back to the original context. This is particularly true when writing Tcl scripts with subroutines, where you may want to feel free to complete a completely new context without altering the context of the calling code. ADEdit offers a push and a pop command to save and retrieve contexts to a stack maintained in memory. push saves the complete current contextall of its bindings and selected objectsto the stack. Subsequent push commands save more contexts to the top of the stack, pushing the older contexts further down the stack, allowing for nested subroutines.
pop

reads the context from the top of the stack and restores it to memory as the current context. pop also removes the restored context from the stack. Subsequent pop commands pop more contexts off the stack until the stack is empty, at which point pop returns an error.

Chapter 3 Getting started with ADEdit

33

Chapter 4

ADEdit command reference

This chapter describes each of ADEdits commands in detail. The descriptions are in alphabetical order to make each command easy to find. The preliminary section below lists the commands in logical groups with a short description of each command to help you find commands to match a particular task. Each command in the logical section links to the full command description later in the chapter.

Command groups
ADEdit commands fall into these logical groups. Click on a command name to go to the full description of the command.

General-purpose commands
General-purpose commands perform actions that control overall ADEdit operation or return general information about ADEdit or its host machine. help returns detailed information about one or more ADEdit commands.

quit quits ADEdit. get_adinfo returns information about the join state of ADEdits host machine. set_ldap_timeout sets the time-out used by ADEdits LDAP commands (read and write operations on Active Directory through a binding)

ADEdit context commands

ADEdit context commands set ADEdits domain bindings, report on ADEdits current bindings and object selection, and save and retrieve ADEdits context (which includes both bindings and currently selected objects). bind binds a domain to ADEdit to for subsequent ADEdit commands.

get_bind_info returns information about a domain to which ADEdit is bound. push saves ADEdits current context to ADEdits context stack. pop restores the context from the top of ADEdits context stack to ADEdit. show displays the current context of ADEdit: its bound domains and its currently selected objects. validate_license takes a path specification to the Centrify license container, determines if there is a valid license and stores an indicator in the ADEdit context.

34

Command groups

Utility commands
Utility commands perform useful data retrieval and data conversion tasks. They convert domain names and security principal names from format to format, and manipulate distinguished names. They check with AD to convert between user principal names and distinguished names. They query for local users, look up users by UNIX name, look up security principals by security IDs (SIDs), and convert SIDs to escaped strings. They also return information about users, groups, and group membership and set user passwords. domain_from_dn converts a domains distinguished name (DN) to a dotted name.

dn_from_domain converts a domains dotted name to a distinguished name. get_parent_dn returns the parent of an LDAP path (a distinguished name): it removes the first element of the DN and returns the rest. get_rdn returns the relative DN of an LDAP path: it returns only the first element of the supplied DN. sid_to_escaped_string converts an Active Directory security identifier (SID) to an escaped string. sid_to_uid converts an AD SID to a user ID (UID). principal_to_dn searches Active Directory for a user principal name (UPN) and, if found, returns the corresponding DN. dn_to_principal searches Active Directory for a DN and, if found, returns the corresponding UPN. principal_from_sid searches Active Directory for an SID and returns the security principal associated with the SID. joined_name_to_principal uses adclient to search for a UNIX name and return the security principal associated with that UNIX name. get_schema_guid finds a class or attribute in Active Directory and returns its globally unique identifier (GUID). getent_passwd returns a Tcl list of all entries in the local etc/passwd file. get_pwnam searches the etc/passwd file for a UNIX username and, if found, returns a Tcl list of the passwd profile values associated with the user. set_user_password sets an AD users password. joined_user_in_group uses adclient to check AD to see if a user is in a group. get_group_members returns a Tcl list of members in a group. joined_get_user_membership uses adclient to query AD and returns a Tcl list of groups that a user belongs to.

Chapter 4 ADEdit command reference

35

Command groups

Security descriptor commands

Security descriptor (SD) commands modify SDs and make them readable by humans. explain_sd converts an SD in SDDL format to a human-readable form.

remove_sd_ace removes an access control entry (ACE) from an SD. add_sd_ace adds an access control entry to an SD. set_sd_owner sets the owner of an SD.

Zone commands
Zone commands create, select, and delete zones. They also examine a domains zones, a zones child zones, and a zones field values. Zone commands set a zones field values and assign zone rights to a user or group. create_zone creates a new zone in Active Directory.

get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

Computer role commands

Computer role commands create, select, and delete computer roles. They also examine and modify computer roles and associate computer roles with role assignments. Because ADEdit treats a computer role as a zone, any operations that affect or are affected by zones are affected (if possible) by a computer role when its the currently selected zone. ADEdit uses some zone commands (listed here) to work with computer roles. Some role assignment commands (also listed here) handle associations with role assignments. create_computer_role creates a new computer role in Active Directory.

get_child_zones returns all computer roles hosted by the selected zone. select_zone retrieves a computer role from Active Directory and stores it in memory as the selected zone so other commands can work on it or with it.

ADEdit Programmers Guide

36

Command groups

new_role_assignment creates a new role assignment and associates it with the selected computer role (selected as a zone). list_role_assignments lists user role assignments associated with the selected computer role (selected as a zone). get_role_assignments returns a Tcl list of user role assignments associated with the selected computer role (selected as a zone). get_zone_field retrieves what computer group is associated with the computer role. set_zone_field sets what computer group is associated with the computer role. save_zone saves the selected computer role with its current settings to Active Directory. delete_zone deletes the selected computer role from Active Directory and memory.

Zone user commands

Zone user commands create, select, and delete zone user objects in the currently selected zone. They also list users in the zone, examine and set user fields, and save users to Active Directory. list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user.

get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user. set_zone_user_field sets a field value in the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

Zone group commands

Zone group commands create, select, and delete zone group objects in the currently selected zone. They also list groups in the zone, examine and set zone group fields, and save zone groups to Active Directory. list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group.

Chapter 4 ADEdit command reference

37

Command groups

get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

Zone computer commands

Zone computer commands create, select, and delete zone computer objects in the currently selected zone. They also list computers in the zone, examine and set computer fields, and save computers to Active Directory. list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer.

get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer. save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

ADEdit Programmers Guide

38

Command groups

Role commands
Role commands create, select, and delete role objects in the currently selected zone. They also list roles in the zone, examine and set role fields and rights, and save computers to Active Directory. list_roles returns a list of all roles in the currently selected zone along with object data for each role

get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

Role assignment commands

Role assignment commands create, select, and delete role assignment objects in the currently selected zone. They also list role assignments in the zone, examine and set role assignment fields, and save role assignments to Active Directory. list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment.

get_role_assignments returns a Tcl list of role assignments in the current zone. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment.

Chapter 4 ADEdit command reference

39

Command groups

select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

PAM application commands

PAM application commands create, select, and delete PAM application objects in the currently selected zone. They also list PAM applications in the zone, examine and set PAM application fields, and save PAM applications to Active Directory. list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application.

get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application. set_pam_field sets a field value in the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

DirectAuthorize (DZ) command commands

DZ command commands create, select, and delete DZ command objects in the currently selected zone. They also list DZ commands in the zone, examine and set DZ command fields, and save DZ commands to Active Directory. list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command.

get_dz_commands returns a Tcl list of DZ commands in the current zone.

ADEdit Programmers Guide

40

Command groups

new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory. delete_dz_command deletes the selected DZ command from Active Directory and from memory.

NIS map commands

NIS map commands create, select, and delete NIS map objects in the currently selected zone. They also list NIS maps in the zone, examine, add, and delete NIS map entries, and save NIS maps to Active Directory. list_nis_maps returns a list of all NIS maps in the currently selected zone.

get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

AD object commands
AD object commands create, select, and delete Active Directory objects. They can perform LDAP searches on AD, get and set object attributes (fields), and save objects and attributes to Active Directory. get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects.

Chapter 4 ADEdit command reference

41

Command descriptions

new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

Command descriptions
The rest of the chapter describes each ADEdit command in detail. Commands are in alphabetical order. The syntax of each command shows optional elements in [square brackets]. It shows variables in italics.

ADEdit Programmers Guide

42

Command descriptions

add_command_to_role
The add_command_to_role command adds a DirectAuthorize (DZ) command to the currently selected role stored in memory. The command must already exist. You can create DZ commands using new_dz_command.
add_command_to_role does not change the role as it is stored Active Directory; it changes the role only in memory. You must save the role before the added command takes effect in AD. If you select another role or quit ADEdit before saving the role, any DZ commands youve added since the last save wont take effect. add_command_to_role

will only work if a tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
add_command_to_role command[/zonename]

Abbreviation
acr

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument Type Description Required. The name of an existing DZ command to add to the currently selected role followed by an optional slash (/) and the zone name where the DZ command is defined. If zonename isnt present, ADEdit looks in the currently selected zone for the command.

command[/zonename] string

Return value
This command returns nothing if successful.

Examples
add_command_to_role basicshell/global

adds the DZ command basicshell, defined in the global zone, to the currently selected role.

Chapter 4 ADEdit command reference

43

Command descriptions

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

44

Command descriptions

add_map_entry
The add_map_entry command adds an entry to the currently selected NIS map stored in memory. To change an existing entry in a NIS map, use delete_map_entry to remove the entry, then add the revised version using add_map_entry.
add_map_entry

changes the NIS map in memory and in Active Directory. You do not need to save the NIS map for the added entry to take effect in AD.

Syntax
add_map_entry key value

Abbreviation
ame

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument key value Type string string Description Required. The key of the NIS map entry. Required. The value of the NIS map entry.

Return value
This command returns nothing if successful.

Examples
add_map_entry calla yosemite.acme.com

adds the NIS map entry calla, with a value of yosemite.acme.com to the currently selected NIS map.

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map.

Chapter 4 ADEdit command reference

45

Command descriptions

select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

46

Command descriptions

add_object_value
The add_object_value command adds a value to a multi-valued field (attribute) of a specified Active Directory (AD) object in Active Directory. It works only on the object in AD, not on the currently selected AD object in memory (if there is one). If the added value isnt valid, AD will report an error and add_object_value wont save the value. This command is useful for fields that may be very largemembers of a group, for example.

Syntax
add_object_value dn field value

Abbreviation
aov

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument dn field Type string string Description Required. The distinguished name (DN) of the AD object in which to add a value. Required. The name of a multi-valued field in the currently selected AD object to which to add the value. This can be any field that is valid for the type of the currently selected AD object. Required. The value to add to the field. The type of value depends on the field specified by field.

value

string

Return value
This command returns nothing if successful.

Examples
add_object_value cn=groups,dc=acme,dc=com users adam.avery

adds the value adam.avery to the users field of the object specified by the DN.

Chapter 4 ADEdit command reference

47

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

48

Command descriptions

add_pamapp_to_role
The add_pamapp_to_role command adds a plug-in authentication module (PAM) application to the currently selected role stored in memory. The PAM application must already exist. You can create PAM applications using new_pam_app.
add_pamapp_to_role does not change the role as it is stored Active Directory; it changes the

role only in memory. You must save the role before the added PAM application takes effect in AD. If you select another role or quit ADEdit before saving the role, any PAM applications youve added since the last save wont take effect.
add_pamapp_to_role will

only work if a tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
add_pamapp_to_role app[/zonename]

Abbreviation
apr

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument app[/zonename] Type string Description Required. The name of an existing PAM application to add to the currently selected role followed by an optional slash (/) and the zone name where the PAM application is defined. If zonename isnt present, ADEdit looks in the currently selected zone for the PAM application.

Return value
This command returns nothing if successful.

Examples
add_pamapp_to_role login-all

adds the PAM application login-all, defined in the currently selected zone, to the currently selected role.

Chapter 4 ADEdit command reference

49

Command descriptions

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

50

Command descriptions

add_sd_ace
The add_sd_ace command adds an access control entry (ACE) in ACE string form to a security descriptor (SD) in SDDL (security descriptor description language) form. The command takes an ACE string and an SDDL string. The command writes the ACE string there. The command returns an SDDL string that includes the added ACE string.

Syntax
add_sd_ace sddl_string ace_string

Abbreviation
ase

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument sddl_string ace_string Type string string Description Required. A security descriptor in SDDL format. Required. An access control entry in ACE string form (which is always enclosed in parentheses)

Return value
This command returns an SD in SDDL format if successful.

Examples
This example adds an ACE string to an SDDL. The ACE string to add is at the end of the command:
add_sd_ace

O:DAG:DAD:AI(A;;RCWDWOCCDCLCSWRPWPLOCR;;;DA)(OA;;CCDC;bf967aba0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967a9c-0de6-11d0-a28500aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a768-00aa006e0529;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;5f20201079a5-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;bf967aba-0de6-

Chapter 4 ADEdit command reference

51

Command descriptions

11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-902000c04fc2d4cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-9020-00c04fc2d3cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;037088f80ae1-11d2-b422-00a0c968f939;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e00a0c983f608;bf967a86-0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a9c-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967aba0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;LC;; ;RU)(A;CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA) (A;;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;SY) returns:

O:DAG:DAD:AI(A;;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;SY)(A;;RCWDWOCCDCLCSWRPWPLOCR;; ;DA)(OA;;CCDC;bf967aba-0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967a9c0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c16420020c0-11d0-a768-00aa006e0529;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-902000c04fc2d4cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-9020-00c04fc2d4cf;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f4279a2-11d0-9020-00c04fc2d3cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b42200a0c968f939;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a86-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967a9c0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e00a0c983f608;bf967aba-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;LC;;;RU)(A; CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA)

ADEdit Programmers Guide

52

Command descriptions

Related commands

explain_sd converts an SD in SDDL format to a human-readable form. remove_sd_ace removes an access control entry (ACE) from an SD. set_sd_owner sets the owner of an SD.

Chapter 4 ADEdit command reference

53

Command descriptions

bind
The bind command binds ADEdit to a domain. Multiple bind commands can bind ADEdit to multiple domains in multiple forests. ADEdit must be bound to at least one domain before its commands have any effect on Active Directory or DirectControl. When ADEdit is bound to multiple domains, its commands may work on any of those domains. You can use bind to bind to any domain for which the DNS can resolve a name and for which you have log-in permission. ADEdits host machine need not be joined to a domain for ADEdit to bind to and work on that domain. You can optionally specify a server in the domain to bind to, in which case ADEdit binds to that domain controller. If you dont specify a server, ADEdit automatically binds to the closest, fastest domain controller. You can use options to request automatic binding to a global catalog (GC) domain controller or to a writable domain controller. can authorize connection to a domain controller in three different ways (if you dont provide a -machine option): If you provide no user or password arguments, bind uses for authorization the username and password stored in the current Kerberos credential cache on ADEdits host machine.
bind

If you provide a user argument with no accompanying password argument, bind in interactive mode prompts you for a password, then uses the user argument along with your entered password for authorization. If you provide a user argument with an accompanying password argument, bind uses the user and password arguments for authorization.

If you provide a -machine option, ADEdit authenticates using ADEdits host machine credentials. You cannot provide user or password arguments if the -machine option is present. Note that you must have read permission on the hosts credential files to use this option, so you must typically have root permissions to use the option.

Syntax
bind [-gc] [-write] [-machine] [server@]domain [user [password]]

Abbreviation
None.

ADEdit Programmers Guide

54

Command descriptions

Options
This command takes the following options:
Option -gc Description Requests an automatic binding (a bind command with no specified domain controller) to a global catalog (GC) domain controller. This argument has no effect if theres a domain controller specified using the server argument. Requests an automatic binding (no specified domain controller) to a writable domain controller. This argument has no effect if theres a domain controller specified using the server argument. Binds using ADEdits host machines credentials. Note that most machine accounts have only read permission, not write permission for Active Directory. Note also that the ADEdit user must have read permission on this machines keytab and credentials cache for this option to work. Only the root typically has this right.

-write

-machine

Arguments
This command takes the following arguments:
Argument [server]@domain Type string Description Required. The domain to bind to. If you want to specify a domain controller to connect to, precede the domain with the name of the domain controllers server followed by the @ symbol. If you dont specify a domain controller, bind performs an automatic binding to the domain controller that ADEdit determines is most optimal for binding. Optional. The username to use when logging into the domain controller. If this argument is not present and the -machine option is also not present, adedit logs in using the ADEdit users credentials. If -machine is present, you cannot use this argument. Optional. Requires the user argument to be present. The password to use when logging in to the domain controller as user.

[user]

string

[password]

string

Return value
This command returns no value.

Examples
bind acme.com administrator #3gEgh^&4

binds ADEdit to the domain acme.com, logging in as administrator with the password #3gEgh^&4. Note that a password that includes Tcl-special characters such as $ may trigger replacement that modifies the password. To ensure that a password isnt altered by the Tcl interpreter, enclose the password in braces ({}).

Chapter 4 ADEdit command reference

55

Command descriptions

Related commands
These commands perform actions related to this command: get_bind_info returns information about a domain to which ADEdit is bound.

show returns the current context of ADEdit: its bound domains and its currently selected objects. push saves ADEdits current context to ADEdits context stack. pop restores the context from the top of ADEdits context stack to ADEdit.

ADEdit Programmers Guide

56

Command descriptions

create_computer_role
The create_computer_role command creates a new computer role in Active Directory. It does not store the new computer role in memory nor set it as the currently selected ADEdit computer role. To manage the computer role, you must select it using select_zone and then use zone commands to work with the computer roles fields. To associate role assignments with the new computer role, you must select the computer role and then use new_role_assignment.

Syntax
create_computer_role computer_role_path group_upn

Abbreviation
ccr

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument computer_role_path Type string Description Required. A path to the new computer role. The path consists of the hosting zones distinguished name followed by a slash and the name of the new computer role. Required. The user principal name (UPN) of a computer group in Active Directory to associate with this computer role. This computer group defines the set of computers in which this computer role functions. The computer group must be available within the computer roles host domain.

group_upn

string

Return value
This command returns no value if successful.

Examples
create_computer_role {CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com/LinuxComputers} [email protected]

This command creates a new computer role named LinuxComputers in the global zone of acme.com. The computer role is defined by the computer group linux_computers which is defined in acme.com.

Chapter 4 ADEdit command reference

57

Command descriptions

Related commands

get_child_zones returns all computer roles hosted by the selected zone. select_zone retrieves a computer role from Active Directory and stores it in memory as the selected zone so other commands can work on it or with it. new_role_assignment creates a new role assignment and associates it with the selected computer role (selected as a zone). list_role_assignments lists user role assignments associated with the selected computer role (selected as a zone). get_role_assignments returns a Tcl list of user role assignments associated with the selected computer role (selected as a zone). get_zone_field retrieves what computer group is associated with the computer role. set_zone_field sets what computer group is associated with the computer role. save_zone saves the selected computer role with its current settings to Active Directory. delete_zone deletes the selected computer role from Active Directory and memory.

ADEdit Programmers Guide

58

Command descriptions

create_zone
The create_zone command creates a new zone in Active Directory. It does not store the new zone in memory nor set it as the currently selected ADEdit zone. To manage the zone, you must select it using select_zone and then use zone commands. This command can create a number of different types of zones and can set them up using a variety of different schemas. When create_zone is invoked, it checks to determine if there is a valid license. The first place it looks is the ADEdit context for a valid license indicator (see the validate_license command) for the forest. If an indicator is not in the context, the create_zone command checks for a valid license as follows: Bind to the global catalog (GC) domain controller, search the forest for the license container and validate the license.

Bind to the current domain, search for the license container and validate the license.

If it finds a valid license, it stores an indicator in the current context and creates the new zone. If it does not find a valid license, create_zone reports No valid license found and exits.

Syntax
create_zone [-ou] zone_type path [schema_type]

Abbreviation
cz

Options
This command takes the following option:
Option -ou Description Creates the new zone as an organizational unit object. If not present, the new zone is created as a container object. Note that the parent container determines what type of object the zone can be. If the parent container is a generic container object, the zone must be a container object. If the parent container is an organizational unit object, the zone can be either an organizational unit object or a container object.

Chapter 4 ADEdit command reference

59

Command descriptions

Arguments
This command takes the following arguments:
Argument zone_type Type string Description Required. Takes the following possible values: tree specifies a zone capable of being a parent or child zone. classic3 specifies a classic zone that is compatible with DirectControl 3 and later versions. classic4 specifies a classic zone that is compatible with DirectControl 4 and later versions computer specifies a computer-level exception (in essence a zone consisting of a single computer for ADEdit purposes) Required. A path to the new zone. The path consists of the new zones distinguished name (DN) and (if a computer override) the machine name for the computer. Optional. The type of schema to use for the new zone. Can be any of three values: sfu specifies the SFU (Services For UNIX) schema. It may be used for tree, classic3, and classic4 zone types only. If its used for a tree zone, it may only be the root of the tree. std specifies the dynamic schema. It may be used for all zone types. This is the default schema unless ADEdit detects the RFC2307 schema in place. rfc specifies the RFC2307 schema. It may be used for all zone types. This is the default schema if ADEdit detects that RFC2307 is installed and the domain is at Windows 2003 functional level. If none of these values is present, the default is either std or rfc as described above.

path

string

schema_type

string

Return value
This command returns no value if successful.

Examples
create_zone tree CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com std

This command creates a new zone that is capable of being a parent or a child named global in the domain acme.com. It uses the dynamic schema for the zone.

Related commands

get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone.

ADEdit Programmers Guide

60

Command descriptions

get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer. validate_license indicates whether there is a valid license in the Centrify license container.

Chapter 4 ADEdit command reference

61

Command descriptions

delegate_zone_right
The delegate_zone_right command delegates a zone administrative right for the currently selected zone to a security principal (user or group). Zone rights allow a user or group to use and manage a zone.

Syntax
delegate_zone_right right principal_upn

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument right Type string Description Required. The right to delegate. Possible values: change_zone: change zone properties add_user: add users to the zone add_group: add groups to the zone join: join computers to the zone delete_zone: remove this zone delete_user: remove users from this zone delete_group: remove groups from this zone delete_computer: remove computers from this zone change_user: modify user profiles in this zone change_group: modify group profiles in this zone change_computer: modify computer profiles in this zone nisservers: allow computers to respond to NIS client requests import: import users and groups into this zone enable_dz: initialize DirectAuthorize (DZ) data add_remove_nismap_entry: add or remove NIS map entries modify_nismap_entry: modify NIS map entries remove_nismap: remove NIS maps Required. The user principal name (UPN) of a user or group in Active Directory to delegate this right to.

principal_upn

string

Return value
This command returns no value if successful.

ADEdit Programmers Guide

62

Command descriptions

Examples
delegate_zone_right add_user [email protected]

delegates the right to add users to the currently selected zone to Adam Avery.

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory.

Chapter 4 ADEdit command reference

63

Command descriptions

delete_dz_command
The delete_dz_command command deletes the currently selected DZ command from Active Directory and also from memory. After deletion there is no currently selected DZ command in memory.

Syntax
delete_dz_command

Abbreviation
dldzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_dz_command

deletes the currently selected DZ command from Active Directory and from memory.

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. get_dz_commands returns a Tcl list of DZ commands in the current zone. new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory.

ADEdit Programmers Guide

64

Command descriptions

delete_map_entry
The delete_map_entry command deletes an entry from the currently selected NIS map stored in memory.
delete_map_entry

changes the NIS map in memory and in Active Directory. You do not need to save the NIS map for the deleted entry to take effect in AD.

Syntax
delete_map_entry key:index

Abbreviation
dlme

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument key:index Type string Description Required. The key of the NIS map entry to delete followed by a colon (:) and the index number of the key.

Return value
This command returns nothing if successful.

Examples
delete_map_entry calla:1

deletes the NIS map entry with the key value calla and index number 1 from the currently selected NIS map.

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map.

Chapter 4 ADEdit command reference

65

Command descriptions

list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

66

Command descriptions

delete_nis_map
The delete_nis_map command deletes the currently selected NIS map from Active Directory and also from memory. After deletion there is no currently selected NIS map in memory.

Syntax
delete_nis_map

Abbreviation
dlnm

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_nis_map

deletes the currently selected NIS map from Active Directory and from memory.

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map.

Chapter 4 ADEdit command reference

67

Command descriptions

save_nis_map saves the selected NIS map with its current entries to Active Directory.

ADEdit Programmers Guide

68

Command descriptions

delete_object
The delete_object command deletes the currently selected Active Directory (AD) object from AD and also from memory. After deletion there is no currently selected AD object in memory.

Syntax
delete_object

Abbreviation
dlo

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_object

deletes the currently selected AD object from Active Directory and from memory.

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object.

Chapter 4 ADEdit command reference

69

Command descriptions

save_object saves the selected AD object with its current settings to Active Directory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

70

Command descriptions

delete_pam_app
The delete_pam_app command deletes the currently selected PAM application from Active Directory and also from memory. After deletion there is no currently selected PAM application in memory.

Syntax
delete_pam_app

Abbreviation
dlpam

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_pam_app

deletes the currently selected PAM application from Active Directory and from memory.

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application. set_pam_field sets a field value in the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory.

Chapter 4 ADEdit command reference

71

Command descriptions

delete_role
The delete_role command deletes the currently selected role from Active Directory and also from memory. After deletion there is no currently selected role in memory.

Syntax
delete_role

Abbreviation
dlr

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_role

deletes the currently selected role from Active Directory and from memory.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role.

ADEdit Programmers Guide

72

Command descriptions

add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory.

Chapter 4 ADEdit command reference

73

Command descriptions

delete_role_assignment
The delete_role_assignment command deletes the currently selected role assignment from Active Directory and also from memory. After deletion there is no currently selected role assignment in memory.

Syntax
delete_role_assignment

Abbreviation
dlra

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_role_assignment

deletes the currently selected role assignment from Active Directory and from memory.

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment. get_role_assignments returns a Tcl list of role assignments in the current zone. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory.

ADEdit Programmers Guide

74

Command descriptions

delete_sub_tree
The delete_sub_tree command deletes an object and all of its children from Active Directory (AD). WARNING: This is a very powerful command, and can cause a lot of damage if used incorrectly. Its similar to rm -rf * in UNIX. In interactive mode, ADEdit will ask for confirmation before executing this command. If used in a script, ADEdit will not ask for confirmation. This command is useful for deleting corrupted zones. Youd normally use select_zone and then delete_zone to delete a zone. If the zone is damaged, though, select_zone might not work. In that case, delete_sub_tree will do the job.

Syntax
delete_sub_tree dn

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument dn Type Description

distin- Required. The distinguished name of the object (with all of its children) to guished remove from AD. name (DN)

Return value
This command returns nothing if successful.

Examples
delete_sub_tree CN=marketing,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com

deletes the currently selected the zone marketing with all of its children from Active Directory.

Chapter 4 ADEdit command reference

75

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory.

ADEdit Programmers Guide

76

Command descriptions

delete_zone
The delete_zone command deletes the currently selected zone from Active Directory and also from memory. After deletion there is no currently selected zone in memory. This command is an LDAP sub-tree delete operation. If the zone contains other zones (not child zones based on parent pointers set in the child zones, but zones that are contained within the deleted zone in Active Directory), then the contained zones are also deleted. In ADEdits interactive mode, entering this command returns a confirmation prompt from ADEdit before execution. In a Tcl script, this command executes without confirmation. Use it cautiously in a script.

Syntax
delete_zone

Abbreviation
dlz

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_zone

deletes the currently selected zone or computer role from Active Directory and from memory.

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone.

Chapter 4 ADEdit command reference

77

Command descriptions

get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory. delegate_zone_right delegates a zone use right to a specified user or computer.

ADEdit Programmers Guide

78

Command descriptions

delete_zone_computer
The delete_zone_computer command deletes the currently selected zone computer from Active Directory and also from memory. After deletion there is no currently selected zone computer in memory.

Syntax
delete_zone_computer

Abbreviation
dlzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_zone_computer

deletes the currently selected zone computer from Active Directory and from memory.

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer. get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer.

Chapter 4 ADEdit command reference

79

Command descriptions

save_zone_computer saves the selected zone computer with its current settings to Active Directory.

ADEdit Programmers Guide

80

Command descriptions

delete_zone_group
The delete_zone_group command deletes the currently selected zone group from Active Directory and also from memory. After deletion there is no currently selected zone group in memory.

Syntax
delete_zone_group

Abbreviation
dlzg

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_zone_group

deletes the currently selected zone group from Active Directory and from memory.

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group. get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory.

Chapter 4 ADEdit command reference

81

Command descriptions

delete_zone_user
The delete_zone_user command deletes the currently selected zone user from Active Directory and also from memory. After deletion there is no currently selected zone user in memory.

Syntax
delete_zone_user

Abbreviation
dlzu

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
delete_zone_user

deletes the currently selected zone user from Active Directory and from memory.

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user. get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user. set_zone_user_field sets a field value in the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory.

ADEdit Programmers Guide

82

Command descriptions

dn_from_domain
The dn_from_domain command takes a domain name in dotted form (acme.com, for example) and converts it to a distinguished name (DN). This conversion doesnt require lookup in Active Directory; its a simple text conversion.

Syntax
dn_from_domain domain_name

Abbreviation
dnfd

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument domain_name Type string Description Required. A dotted domain name (acme.com, for example)

Return value
This command returns a domain name as a distinguished name.

Examples
dn_from_domain acme.com

returns: dc=acme,dc=com

Related commands

domain_from_dn converts a domains distinguished name (DN) to a dotted name.

Chapter 4 ADEdit command reference

83

Command descriptions

dn_to_principal
The dn_to_principal command takes the distinguished name (DN) of a security principal (user, computer, or group), searches Active Directory for the principal, and if it finds the principal returns the user principal name (UPN) of the principal.

Syntax
dn_to_principal principal_dn

Abbreviation
dntp

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument principal_dn Type string Description Required. The distinguished name (DN) of a security principal.

Return value
This command returns a user principal name. If the command doesnt find the specified security principal in Active Directory, it presents a message that it didnt find the principal.

Examples
dn_to_principal cn=brenda butler,cn=users,dc=acme,dc=com

returns: [email protected]

Related commands

principal_to_dn searches Active Directory for a user principal name (UPN) and, if found, returns the corresponding distinguished name (DN). principal_from_sid searches Active Directory for an SID and returns the security principal associated with the SID.

ADEdit Programmers Guide

84

Command descriptions

domain_from_dn
The domain_from_dn command takes a distinguished name (DN) that contains a domain and returns the domain name in dotted form (acme.com, for example). This conversion doesnt require lookup in Active Directory; its a simple text conversion.

Syntax
domain_from_dn dn

Abbreviation
dfdn

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument dn Type string Description Required. A distinguished name that contains a domain.

Return value
This command returns a domain name in dotted form such as acme.com. If the distinguished name doesnt contain DC values, the command returns a notice that the DC values are missing.

Examples
dfdn cn=johndoe,cn=users,dc=acme,dc=com

returns: acme.com

Related commands

dn_from_domain converts a domains dotted name to a distinguished name.

Chapter 4 ADEdit command reference

85

Command descriptions

explain_sd
The explain_sd command takes a security descriptor (SD) in security descriptor description language (SDDL) form and returns a human-readable form of the SD.

Syntax
explain_sd sddl_string

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument sddl_string Type string Description Required. A security descriptor in SDDL format.

Return value
This command returns text that describes the supplied SD in human-readable form.

Examples
explain_sd O:DAG:DAD:AI(A;;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;SY)(A;;RCWDWOCCDCLCSWRPWPLOCR;; ;DA)(OA;;CCDC;bf967aba-0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967a9c0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c16420020c0-11d0-a768-00aa006e0529;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-902000c04fc2d4cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-9020-00c04fc2d4cf;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f4279a2-11d0-9020-00c04fc2d3cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b42200a0c968f939;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a86-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967a9c0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-

ADEdit Programmers Guide

86

Command descriptions

00a0c983f608;bf967aba-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;LC;;;RU)(A; CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA)

returns:
Owner: Domain Admins Group: Domain Admins Dacl: inherit supported, Allow | | delete,read SD,write DACL,change owner,create child,delete child,list children,self write,read property,write property,delete tree,list object,control access, | | | System Allow | | read SD,write DACL,change owner,create child,delete child,list children,self write,read property,write property,list object,control access, | | | Domain Admins Allow | | create child,delete child, | User | | Account operators Allow | | create child,delete child, | Group | | Account operators Allow | | create child,delete child, | Print-Queue | | Print operators Allow | | read SD,list children,read property,list object, | | | Authenticated users Allow | | create child,delete child, | inetOrgPerson | | Account operators Allow | inherit,inherit ony,inherited, | read property, | User-AccountRestrictions | inetOrgPerson | pre win2k Allow | inherit,inherit ony,inherited, | read property, | User-AccountRestrictions | User | pre win2k Allow | inherit,inherit ony,inherited, | read property, | User-Logon | inetOrgPerson | pre win2k Allow | inherit,inherit ony,inherited, | read property, | User-Logon | User | pre win2k Allow | inherit,inherit ony,inherited, | read property, | Membership | inetOrgPerson | pre win2k Allow | inherit,inherit ony,inherited, | read property, | Membership | User | pre win2k Allow | inherit,inherit ony,inherited, | read property, | General-Information | inetOrgPerson | pre win2k Allow | inherit,inherit ony,inherited, | read property, | General-Information | User | pre win2k Allow | inherit,inherit ony,inherited, | read property, | RAS-Information | inetOrgPerson | pre win2k Allow | inherit,inherit ony,inherited, | read property, | RAS-Information | User | pre win2k Allow | inherit,inherit ony,inherited, | read property, | Token-Groups | Computer | Enterprise Domain Controllers Allow | inherit,inherit ony,inherited, | read property, | Token-Groups | Group | Enterprise Domain Controllers Allow | inherit,inherit ony,inherited, | read property, | Token-Groups | User | Enterprise Domain Controllers Allow | inherit,inherit ony,inherited, | read SD,list children,read property,list object, | | inetOrgPerson | pre win2k Allow | inherit,inherit ony,inherited, | read SD,list children,read property,list object, | | Group | pre win2k Allow | inherit,inherit ony,inherited, | read SD,list children,read property,list object, | | User | pre win2k Allow | inherit,inherited, | read property,write property,control access, |

Chapter 4 ADEdit command reference

87

Command descriptions

Private-Information | | Self Allow | inherit,inherited, | delete,read SD,write DACL,change owner,create child,delete child,list children,self write,read property,write property,delete tree,list object,control access, | | | Enterprise Admins Allow | inherit,inherited, | list children, | | | pre win2k Allow | inherit,inherited, | delete,read SD,write DACL,change owner,create child,list children,self write,read property,write property,list object,control access, | | | Administrators

Related commands

remove_sd_ace removes an access control entry (ACE) from an SD. add_sd_ace adds an access control entry to an SD. set_sd_owner sets the owner of an SD.

ADEdit Programmers Guide

88

Command descriptions

get_adinfo
The get_adinfo command returns information about the host machines current join state. It returns information about the joined domain, the joined zone, or the name the host machine is joined under.

Syntax
get_adinfo domain|zone|host

Abbreviation
adinfo

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument domain|zone|host Type string Description Required. Takes one of three possible values: domain returns the name of the currently joined domain zone returns the distinguished name of the currently joined zone host returns the name under which ADEdits current host machine is joined

Return value
This command returns a domain name, zone name, or machine name depending on the provided argument.

Examples
get_adinfo domain

returns: acme.com
adinfo zone

returns: CN=default,CN=Zone,CN=Centrify,CN=Program

Data,DC=acme,DC=com

Related commands
None.

Chapter 4 ADEdit command reference

89

Command descriptions

get_bind_info
The get_bind_info command returns information about one of ADEdits currently bound domains. It can return the name of the domains forest, the name of the server bound within the domain, the security identifier (SID) of the domain, and the functional level of the domain or the domains forest.

Syntax
get_bind_info domain forest|server|sid|domain_level|forest_level

Abbreviation
gbi

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument domain forest|server|sid| domain_level| forest_level Type string string Description Required. The name of the domain for which to get information. Required. Takes one of five possible values: forest returns the name of the forest that contains the bound domain server returns the name of the domain server to which ADEdit is bound in the domain sid returns the SID (security identifier) of the bound domain domain_level returns the functional level of the bound domain, represented by an integer value: -1: unknown functional level 0: Windows 2000 1: Windows 2003, interim level 2: Windows 2003 3: Windows 2008 4: Windows 2008 release 2 forest_level returns the functional level of the forest that contains the bound domain

Return value
This command returns a forest name, server name, security identifier, or functional level depending on the provided argument.

ADEdit Programmers Guide

90

Command descriptions

Examples
get_bind_info acme.com server

returns: adserve02.acme.com

Related commands
These commands perform actions related to this command: bind binds a domain to ADEdit to for subsequent ADEdit commands.

show returns the current context of ADEdit: its bound domains and its currently selected objects. push saves ADEdits current context to ADEdits context stack. pop restores the context from the top of ADEdits context stack to ADEdit.

Chapter 4 ADEdit command reference

91

Command descriptions

get_child_zones
The get_child_zones command returns a Tcl list of the child zones, associated computer roles, and computer zones of the currently selected zone in memory. It only works with tree zones.

Syntax
get_child_zones [-tree] [-crole] [-computer]

Abbreviation
gcz

Options
This command takes any one of the following options:
Option -tree -crole -computer Description Return a Tcl list of the current zones child zones. Return a Tcl list of the current zones hosted computer roles. Return a Tcl list of the current zones computer zones.

Note that if none of these options is present, get_child_zones returns child zones, computer roles, and computer zones.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of child zones, computer roles, and/or computer zones depending on the options used or not used.

Examples
get_child_zones

returns:
{CN=cz1,CN=Zones,CN=Centrify,CN=Program Data,DC=eel,DC=nest} {CN=cz2,CN=Zones,CN=Centrify,CN=Program Data,DC=eel,DC=nest} {CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=eel,DC=nest/ oracle_servers}

Related commands

create_zone creates a new zone in Active Directory.

ADEdit Programmers Guide

92

Command descriptions

get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

Chapter 4 ADEdit command reference

93

Command descriptions

get_dz_commands
The get_dz_commands command checks Active Directory and returns a Tcl list of DirectAuthorize (DZ) command objects defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_dz_commands to output to stdout. Note that get_dz_commands only returns DZ command data for classic4 and tree zones.

Syntax
get_dz_commands

Abbreviation
gdzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of DZ commands defined in the currently selected zone.

Examples
get_dz_commands

returns: root_any

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory.

ADEdit Programmers Guide

94

Command descriptions

delete_dz_command deletes the selected DZ command from Active Directory and from memory.

Chapter 4 ADEdit command reference

95

Command descriptions

get_dzc_field
The get_dzc_field command returns a field (attribute) value from the currently selected DirectAuthorize (DZ) command object stored in memory. does not query Active Directory for the DZ command. If youve changed field values using ADEdit without saving the DZ command to Active Directory, the field value you retrieve using get_dzc_field wont match the same field value for the DZ command stored in Active Directory.
get_dzc_field

will only work if a classic4 or tree zone is the currently selected zone. It will not work in other types of zones.
get_dzc_field

Syntax
get_dzc_field field

Abbreviation
gdzcf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: description: text describing the DZ command. cmd: the UNIX command string (or strings) specifying restricted commands. This can be a string that may include wildcards (*, ? and !), or it may be a regular expression. If using wildcards, a ! before a command string specifies not that string. The form field sets whether this string is interpreted as a regular expression or a string that includes wildcards. path: the path to the commands location. May use wildcards or be a regular expression as described for the cmd field. form: the form of the string used in the cmd and path fields. An integer: 0 is a string that may include wild cards 1 is a regular expression dzdo_runas: a list of users and groups that can run this command under dzdo (DirectAuthorizes version of sudo). Users may be listed by username or user ID (UID). dzsh_runas: a list of users and groups that can run this command under dzsh (DirectAuthorizes restricted environment shell). Users may be listed by username or user ID (UID).

ADEdit Programmers Guide

96

Command descriptions

Argument

Type

Description keep: a comma-separated list of environment variables from the current users environment to keep in addition to the default set of the users environment variables that are retained. (The default keep set is defined in the dzdo.env_keep parameter of centrifydc.conf).)These environment variables are used by the commands specified in cmd. This field has effect only if the flag fields 16 flag is set. del: a comma-separated list of environment variables from the current users environment to delete in addition to the default set of environment variables specified to delete. (The default delete set is defined in the dzdo.env_delete parameter of centrifydc.conf.) These environment variables are used by the commands specified in cmd. This field has effect only if the flag fields 16 flag is not set. add: a comma-separated list of environment variables to add to the final set of environment variables resulting from the keep or delete sets described in the keep and delete fields. pri: the command priority for this DZ command object, used for handling multiple matches for DZ commands specified by wild cards. If commands specified by this DZ command object match commands specified by another DZ command object, the DZ command object with the higher command priority prevails. This field takes an integer value; the higher the number, the higher the priority. umask: the umask value used to define who can execute the command. This is a 3-digit octal value that defines read, write, or execute permission for owner, group, and other. The left digit defines owner execution rights, the middle digit defines group execution rights, the right digit defines other execution rights. Each digit is a combination of binary flags, one flag for each right: 4 is read 2 is write 1 is execute These values add together in a digit to define rights available for the digits entity: for example, a 600(4+2) is both read and write for the owner, but nothing for the group or others.

Chapter 4 ADEdit command reference

97

Command descriptions

Argument

Type

Description flags: specifies different properties of the command. This value is an integer from 0 to 31 that represents a combination of binary flags, one flag for each property: 1 is allow nested command execution (or not if not set) 2 is authentication required with users password (cant be set simultaneously with the 4 flag). If neither 2 nor 4 is set, authentication is not required. 4 is authentication required, run as the targets password (cant be set simultaneously with the 2 flag). If neither 2 nor 4 is set, authentication is not required. 8 is preserve group membership (or dont if not set). 16 is reset environment variables for the command, deleting those variables specified in the dsdo.env_delete parameter of centrifydc.conf, exempting those variables specified in the keep field. If this flag is not set, the command is set to remove the unsafe environment variables specified in the dsdo.env_delete parameter of centrifydc.conf along with any additional environment variables specified by the del field. These values add together to create the flags value. 5, for example, is allow nested command execution and authentication required, run as the targets password (1+4). createTime: the time and date this DZ command was created, returned in generalized time format modifyTime: the time and date this DZ command was created, returned in generalized time format dn: the DZ commands distinguished name

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_dzc_field dzdo_runas

returns: root

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. get_dz_commands returns a Tcl list of DZ commands in the current zone. new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. set_dzc_field sets a field value in the currently selected DZ command.

ADEdit Programmers Guide

98

Command descriptions

save_dz_command saves the selected DZ command with its current settings to Active Directory. delete_dz_command deletes the selected DZ command from Active Directory and from memory.

Chapter 4 ADEdit command reference

99

Command descriptions

get_group_members
The get_group_members command checks with Active Directory, recursively expands a specified group by opening groups that are members of groups, and returns a Tcl list of the users in the specified group.

Syntax
get_group_members group_UPN

Abbreviation
ggm

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument group_UPN Type string Description Required. The user principal name (UPN) of the group to check for user membership.

Return value
This command returns a Tcl list of group members.

Examples
get_group_members [email protected]

returns [email protected]

[email protected]

Related commands

joined_user_in_group checks AD to see if a user is in a group. joined_get_user_membership returns a Tcl list of groups that a user belongs to.

ADEdit Programmers Guide

100

Command descriptions

get_nis_map
The get_nis_map command returns a Tcl list containing the entries for the currently selected NIS map stored in memory. does not query Active Directory for this NIS map, but changing map entries using add_map_entry and delete_map_entry changes both selected NIS map in memory and the corresponding NIS map in Active Directory so their contents should match.
get_nis_map

Syntax
get_nis_map

Abbreviation
gnm

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of NIS map entries. Each entry contains: The key

The instance number of the key (there may be multiple entries with the same key) The value

Each entry component is separated from the next by a colon (:).

Examples
get_nis_map

returns: {Argo:1:

tweety.acme.com} {Buster:1:

bigbird.acme.com}

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map.

Chapter 4 ADEdit command reference

101

Command descriptions

select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

102

Command descriptions

get_nis_map_field
The get_nis_map_field command returns a field (attribute) value from the currently selected NIS map stored in memory. does not query Active Directory for the NIS map. If youve changed field values using ADEdit without saving the NIS map to Active Directory, the field value you retrieve using get_nis_map_field wont match the same field value for the NIS map stored in Active Directory.
get_nis_map_field

Syntax
get_nis_map_field field

Abbreviation
gnmf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: createTime: the time and date this NIS map was created, returned in generalized time format modifyTime: the time and date this NIS map was created, returned in generalized time format dn: the NIS maps distinguished name

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_nis_map_field createTime

returns: 20110525163718.0Z

Related Commands

list_nis_maps returns a list of all NIS maps in the currently selected zone.

Chapter 4 ADEdit command reference

103

Command descriptions

get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

104

Command descriptions

get_nis_maps
The get_nis_maps command checks Active Directory and returns a Tcl list of NIS maps defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_nis_maps to output to stdout.

Syntax
get_nis_maps

Abbreviation
gnms

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of NIS maps defined in the currently selected zone.

Examples
get_nis_maps

returns: Aliases

Printers Services

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map.

Chapter 4 ADEdit command reference

105

Command descriptions

save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

106

Command descriptions

get_object_field
The get_object_field command returns a field (attribute) value from the currently selected Active Directory (AD) object stored in memory. does not query Active Directory for the object. If youve changed field values using ADEdit without saving the object to Active Directory, the field value you retrieve using get_object_field wont match the same field value for the object stored in Active Directory.
get_object_field

Syntax
get_object_field field

Abbreviation
gof

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are anything that may be defined for the type of object currently selected. Special values are: sid: the objects security identifier. guid: the objects globally unique identifier sd: the objects security descriptor createTime: the time and date this object was created, returned in generalized time format modifyTime: the time and date this object was created, returned in generalized time format dn: the objects distinguished name

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_object_field guid

returns: 44918ee7-80bc-4741-95d3-dd189e235ab8

Chapter 4 ADEdit command reference

107

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

108

Command descriptions

get_objects
The get_objects command performs an LDAP search of Active Directory (AD) and returns a Tcl list of the distinguished names (DNs) of all objects that match the search. You specify a container in AD where the search begins and a standard LDAP filter that defines the objects youre searching for. You can control the nature of the search through options that specify whether or not code_objects uses a global catalog (GC) for a forest-wide search, how deep the search goes below the beginning container of the search, and how many objects maximum get_objects will return.

Syntax
get_objects [-gc] [-depth one|sub] [-limit limit] base filter

Abbreviation
go

Options
This command takes the following options:
Option -gc Description Requests a forest-wide search using a global catalog. For this option to work, ADEdit must be bound to a GC using the bind command with its -gc option. If this option is not present, the search is only within the currently bound domains. Specifies how deep to search. This option must be followed by one of two values: one: specifies that the search will search only through objects immediately below the container specified by the argument base. sub: specifies that the search will be full-depth, starting at the container specified by base and continuing through all sub-containers below that level. If this option is not present, the search defaults to the value one. Limits the number of objects returned by the search to the positive integer specified by limit. If this option is not present, the search returns all matching objects without limit.

-depth one|sub

-limit limit

Chapter 4 ADEdit command reference

109

Command descriptions

Arguments
This command takes the following arguments:
Argument base Type Description

distin- Required. The DN of an Active Directory container in which to start the search. guished name (DN) LDAP filter Required. An LDAP filter, a string that uses standard LDAP filter syntax to specify criteria for the search.

filter

Return value
This command returns a Tcl list of DNs of all objects found by the search.

Examples
get_objects cn=users,dc=acme,dc=com (objectclass=*)

returns CN=Builtin,DC=acme,DC=com

CN=Computers,DC=acme,DC=com {OU=Domain Controllers,DC=acme,DC=com} CN=ForeignSecurityPrincipals,DC=acme,DC=com CN=Infrastructure,DC=acme,DC=com CN=LostAndFound,DC=acme,DC=com {CN=NTDS Quotas,DC=acme,DC=com} {CN=Program Data,DC=acme,DC=com} CN=System,DC=acme,DC=com CN=Users,DC=acme,DC=com

Related commands

new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

110

Command descriptions

get_pam_apps
The get_pam_apps command checks Active Directory and returns a Tcl list of plug-in application module (PAM) applications defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_pam_apps to output to stdout. Note that get_pam_apps only returns PAM application data for classic4 and tree zones.

Syntax
get_pam_apps

Abbreviation
gpam

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of PAM applications defined in the currently selected zone. Each element in the string is the name of a PAM application.

Examples
get_pam_apps

returns: login-all

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application. set_pam_field sets a field value in the currently selected PAM application.

Chapter 4 ADEdit command reference

111

Command descriptions

save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

ADEdit Programmers Guide

112

Command descriptions

get_pam_field
The get_pam_field command returns a field (attribute) value from the currently selected plug-in authentication module (PAM) application object stored in memory.
get_pam_field does not query Active Directory for the PAM application. If youve changed

field values using ADEdit without saving the PAM application to Active Directory, the field value you retrieve using get_pam_field wont match the same field value for the PAM application stored in Active Directory. will only work if a classic4 or tree zone is the currently selected zone. It will not work in other types of zones.
get_pam_field

Syntax
get_pam_field field

Abbreviation
gpf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: application: the name of the application allowed to use adclients PAM authentication service. The name can be literal, or it can contain ? or * wildcard characters to specify multiple applications. description: text describing the PAM application. createTime: the time and date this PAM application was created, returned in generalized time format modifyTime: the time and date this PAM application was created, returned in generalized time format dn: the PAM applications distinguished name

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_pam_field application

Chapter 4 ADEdit command reference

113

Command descriptions

returns: ftp The PAM application object specifies ftp as an application that can authenticate using adclients PAM service.

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. set_pam_field sets a field value in the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

ADEdit Programmers Guide

114

Command descriptions

get_parent_dn
The get_parent command takes an LDAP path (a distinguished name (DN)) and returns the parent of the path. In other words, it removes the first element from the DN and returns the rest of the DN.

Syntax
get_parent_dn DN

Abbreviation
gpt

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument DN Type string Description Required. A distinguished name.

Return value
This command returns a distinguished name that is the parent of the supplied distinguished name.

Examples
get_parent_dn CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com

returns: CN=Zones,CN=Centrify,CN=Program

Data,DC=acme,DC=com

Related commands

get_rdn returns the relative distinguished name (DN) of an LDAP path: it returns only the fist element of the supplied DN.

Chapter 4 ADEdit command reference

115

Command descriptions

get_pwnam
The get_pwnam command looks up a UNIX username in the ADEdit host machines etc/ passwd file and, if it finds an entry under that name, returns the profile values of that entry as a Tcl list. get_pwnam uses the NSS layer to perform the lookup, and will work for any user in the etc/passwd file, including root.

Syntax
get_pwnam unix_name

Abbreviation
gpn

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument unix_name Type string Description Required. The UNIX username to search for in etc/passwd.

Return value
This command returns a Tcl list of entry profile values if the command finds the username in etc/passwd. If the command doesnt find the specified user, it presents a message stating so.

Examples
get_pwnam adam

returns: adam returns: root

x 500 500 {Adam Apple} /home/adam /bin/bash

get_pwnam root x 0 0 /root /bin/bash

Related commands

getent_passwd returns a Tcl list of all entries in the local etc/passwd file.

ADEdit Programmers Guide

116

Command descriptions

get_rdn
The get_rdn command takes an LDAP path (a distinguished name (DN)) and returns the relative distinguished name. In other words, it returns only the first element of the supplied DN.

Syntax
get_rdn DN

Abbreviation
grdn

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument DN Type string Description Required. A distinguished name.

Return value
This command returns the first element of the supplied DN.

Examples
get_rdn CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com

returns: CN=global

Related commands

get_parent_dn returns the parent of an LDAP path (a distinguished name): it removes the first element of the DN and returns the rest.

Chapter 4 ADEdit command reference

117

Command descriptions

get_role_apps
The get_role_apps command returns a Tcl list of pluggable authentication module (PAM) applications associated with the currently selected role. does not query Active Directory for the role. If youve changed PAM applications associated with the current role using ADEdit without saving the role to Active Directory, the PAM applications you retrieve using get_role_apps wont match the same PAM applications for the role stored in Active Directory.
get_role_apps

will only work if a classic4 or tree zone is the currently selected zone. It will not work in other types of zones.
get_role_apps

Syntax
get_role_apps

Abbreviation
grap

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of PAM applications associated with the currently selected role. Each PAM applicaton in the list shows the application name followed by a slash (/) and the zone in which the PAM application is defined.

Examples
get_role_apps

returns: ftp/cz1

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role.

ADEdit Programmers Guide

118

Command descriptions

select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

Chapter 4 ADEdit command reference

119

Command descriptions

get_role_assignment_field
The get_role_assignment_field command returns a field (attribute) value from the currently selected role assignment stored in memory. does not query Active Directory for the role assignment. If youve changed field values using ADEdit without saving the role assignment to Active Directory, the field value you retrieve using get_role_assignment_field wont match the same field value for the role assignment stored in Active Directory.
get_role_assignment_field get_role_assignment_field

will only work if a classic4 or tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
get_role_assignment_field field

Abbreviation
graf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: role: the name of the role to assign and the zone in which the role was defined. A slash (/) separates the two values. from: the starting date and time for the role assignment. The date and time is expressed in standard UNIX time. The Tcl clock command manipulates these time values. A value of 0 means no starting date and time for the role assignment. to: the ending date and time for the role assignment. The date and time is expressed in standard UNIX time. The Tcl clock command manipulates these time values. A value of 0 means no ending date and time for the role assignment. createTime: the time and date this role assignment was created, returned in generalized time format modifyTime: the time and date this role assignment was created, returned in generalized time format dn: the role assignments distinguished name

ADEdit Programmers Guide

120

Command descriptions

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_role_assignment_field role

returns: root/global This is the role root defined in the zone global.

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment. get_role_assignments returns a Tcl list of role assignments in the current zone. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

Chapter 4 ADEdit command reference

121

Command descriptions

get_role_assignments
The get_role_assignments command checks Active Directory and returns a Tcl list of role assignments defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_role_assignments to output to stdout. Note that get_role_assignments only returns role assignment data for classic4 and tree zones.

Syntax
get_role_assignments

Abbreviation
gra

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of role assignments defined in the currently selected zone. Each role assignment includes the user principal name (UPN) of the user or group to whom the role is assigned, the name of the role assigned, and the zone in which the role is defined. These three pieces of data are separated from each other by a slash (/).

Examples
get_role_assignments

returns: [email protected]/root/global

[email protected]/login/global

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment.

ADEdit Programmers Guide

122

Command descriptions

get_role_assignment_field reads a field value from the currently selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

Chapter 4 ADEdit command reference

123

Command descriptions

get_role_commands
The get_role_commands command returns a Tcl list of DirectAuthorize (DZ) commands associated with the currently selected role. does not query Active Directory for the role. If youve changed commands associated with the current role using ADEdit without saving the role to Active Directory, the commands you retrieve using get_role_commands wont match the same commands for the role stored in Active Directory.
get_role_commands get_role_commands

will only work if a classic4 or tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
get_role_commands

Abbreviation
grc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of commands associated with the currently selected role. Each command in the list shows the command name followed by a slash (/) and the zone in which the command is defined.

Examples
get_role_commands

returns: pwd/global

ls/global cd/cz1

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role.

ADEdit Programmers Guide

124

Command descriptions

select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

Chapter 4 ADEdit command reference

125

Command descriptions

get_role_field
The get_role_field command returns a field (attribute) value from the currently selected role stored in memory.
get_role_field does not query Active Directory for the role. If youve changed field values

using ADEdit without saving the role to Active Directory, the field value you retrieve using get_role_field wont match the same field value for the role stored in Active Directory.
get_role_field

will only work if a classic4 or tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
get_role_field field

Abbreviation
grf

Options
This command takes no options.

ADEdit Programmers Guide

126

Command descriptions

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: timebox: the hours in the week when the role is enabled. This value is a 42digit hexadecimal number. When represented in binary, each bit represents an hour of the week as described in the appendix Timebox value format on page 308. sysrights: what system rights are granted to the role. This value is an integer from 0 to 15 that represents a combination of binary flags, one for each right: 1 is the right to password login 2 is the right to SSO login (single sign-on, also known as non-password login) 4 is the right to ignore disabled status in Active Directory and log-on even if the account is disabled in AD. 8 is the right to use a full shell. These values add together to create the sysrights value. 6, for example, is SSO login and ignore disabled (2+4). 15 is all system rights enabled (1+2+4+7). description: text describing the role createTime: the time and date this role was created, returned in generalized time format modifyTime: the time and date this role was created, returned in generalized time format dn: the roles distinguished name

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_role_field timebox

returns: 00FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF0 This means that the role is enabled during all hours of the weekdays, but none of the weekends.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role.

Chapter 4 ADEdit command reference

127

Command descriptions

select_role retrieves a role from Active Directory and stores it in memory as the selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

128

Command descriptions

get_roles
The get_roles command checks Active Directory and returns a Tcl list of roles defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_roles to output to stdout. Note that get_roles only returns role data for classic4 and tree zones.

Syntax
get_roles

Abbreviation
getr

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of roles defined in the currently selected zone.

Examples
get_roles

returns: listed

login

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role.

Chapter 4 ADEdit command reference

129

Command descriptions

get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

130

Command descriptions

get_schema_guid
The get_schema_guid command looks up a class or attribute in Active Directory and, if found, returns the globally unique identifier (GUID) of the class or attribute. This command is useful for setting a security descriptor (SD) at a class or attribute level.

Syntax
get_schema_guid schema_name

Abbreviation
gsg

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument schema_name Type string Description Required. The name of a class or attribute.

Return value
This command returns the globally unique identifier (GUID) of the provided schema (class or attribute).

Examples
get_schema_guid MS-DS-Az-Role returns: 8213eac9-9d55-44dc-925c-e9a52b927644

Related commands
None.

Chapter 4 ADEdit command reference

131

Command descriptions

get_zone_computer_field
The get_zone_computer_field command returns a field (attribute) value from the currently selected zone computer stored in memory. does not query Active Directory for the zone computer. If youve changed field values using ADEdit without saving the zone computer to Active Directory, the field value you retrieve using get_zone_computer_field wont match the same field value for the zone computer stored in Active Directory.
get_zone_computer_field

Syntax
get_zone_computer_field field

Abbreviation
gzcf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: cpus: the number of CPUs in the computer enabled: whether the zone computer is enabled in its zone or not. Returns true if enabled, false if not. agentversion: the version of adagent installed on the zone computer dnsname: the domain name service (DNS) name of the zone computer createTime: the time and date this zone computer was created, returned in generalized time format modifyTime: the time and date this zone computer was created, returned in generalized time format dn: the zone computers distinguished name. (Note: if the computer is in an SFU zone, no value is returned for this field.)

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_zone_computer_field dnsname

ADEdit Programmers Guide

132

Command descriptions

returns: printserver.acme.com

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer. get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. set_zone_computer_field sets a field value in the currently selected zone computer. save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

Chapter 4 ADEdit command reference

133

Command descriptions

get_zone_computers
The get_zone_computers command checks Active Directory and returns a Tcl list of zone computers defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_zone_computers to output to stdout.

Syntax
get_zone_computers

Abbreviation
gzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of zone computers defined in the currently selected zone. Each entry in the list is the security identifier (SID) of a computer that you can use to look up that computer.

Examples
get_zone_computers

returns: *S-1-5-21-2076040321-3326545908-468068287-1107

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer.

ADEdit Programmers Guide

134

Command descriptions

save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

Chapter 4 ADEdit command reference

135

Command descriptions

get_zone_field
The get_zone_field command returns a field (attribute) value from the currently selected zone stored in memory.
get_zone_field

does not query Active Directory for this zone. If youve changed field values using ADEdit without saving the zone to Active Directory, the field value you retrieve using get_zone_field wont match the same field value for the zone stored in Active Directory.

Syntax
get_zone_field field

Abbreviation
gzf

Options
This command takes no options.

ADEdit Programmers Guide

136

Command descriptions

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Possible values are: type: The type of this zone (classic 4, tree, etc.) schema: The schema used in this zone. parent (only if the currently selected zone is a tree zone): This zones parent zone. Shows the distinguished name (DN) of a zone. computers (only if the currently selected zone is a computer role): the computer group assigned to the selected computer role. Shows the user principal name (UPN) of the computer group. nisdomain: the name of the NIS domain set up for agentless clients.If not set, the default is the zone name. sfudomain (only if the currently selected zone is an SFU zone): the Windows domain to associate with the SFU zone. Shows a domain name. uidnext: The user ID to start from when auto-assigning UID numbers to new users created in this zone. uidreserved: User ID numbers to reserve and not use for UID auto-assignment if auto-assignment is turned on. Shows an integer (100, for example) or an integer range (1-100, for example). defaultgid: The default primary group to join for a new user created in this zone. Shows a group ID (GID) value. May use environment variables. defaultgecos: The default GECOS data to assign a new user created in this zone. Shows a string that defines the data. May use environment variables. defaulthome: The default home directory to assign a new user created in this zone. Shows a string that defines a path. May use environment variables. defaultshell: The default shell to assign a new user created in this zone. Shows a string that defines the shell. May use environment variables. availableshells: The shells available to choose from when adding a new user to the zone using the console. Shows a string that is a set of shell commands, each separated from the next by a colon (:). For example, /bin/bash:/bin/ csh:/bin/ksh gidnext: The group ID to start from when auto-assigning GID numbers to new users created in this zone. gidreserved: Group ID numbers to reserve and not use for GID autoassignment if auto-assignment is turned on by gidnext. Shows an integer (100, for example) or an integer range (1-100, for example). createTime: the time and date this zone was created, returned in generalized time format modifyTime: the time and date this zone was created, returned in generalized time format dn: the zones distinguished name.

Chapter 4 ADEdit command reference

137

Command descriptions

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_zone_field type

returns: access
gzf schema

returns: std

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

ADEdit Programmers Guide

138

Command descriptions

get_zone_group_field
The get_zone_group_field command returns a field (attribute) value from the currently selected zone group stored in memory. does not query Active Directory for the zone group. If youve changed field values using ADEdit without saving the zone group to Active Directory, the field value you retrieve using get_zone_group_field wont match the same field value for the zone group stored in Active Directory.
get_zone_group_field

Syntax
get_zone_group_field field

Abbreviation
gzgf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Fields are standard etc/group fields for a group account. Possible values are: name: the group name gid: the group ID required: the zone group is required for members in this zone. A user assigned to this group cannot remove the group from their active set of groups. An integer: 1 is required, 0 is not required. createTime: the time and date this zone group was created, returned in generalized time format modifyTime: the time and date this zone group was created, returned in generalized time format dn: the zone groups distinguished name.

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Examples
get_zone_group_field name

returns: padmins

Chapter 4 ADEdit command reference

139

Command descriptions

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group. get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. set_zone_group_field sets a field value in the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

ADEdit Programmers Guide

140

Command descriptions

get_zone_groups
The get_zone_groups command checks Active Directory and returns a Tcl list of zone groups defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_zone_groups to output to stdout.

Syntax
get_zone_groups

Abbreviation
gzg

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of zone groups defined in the currently selected zone. Each entry in the list is the user principal name (UPN) of a group that you can use to look up that group.

Examples
get_zone_groups

returns: [email protected],

[email protected]

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group.

Chapter 4 ADEdit command reference

141

Command descriptions

save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

ADEdit Programmers Guide

142

Command descriptions

get_zone_nss_vars
The get_zone_nss_vars command returns a Tcl list containing the NSS substitution variables for the currently selected zone stored in memory. It only works on tree zones and wont return a value for other zone types. does not query Active Directory for this zone. If youve changed the variables using set_zone_field without saving the zone Active Directory, the variable you retrieve using get_zone_nss_vars wont match the same field variable for the zone stored in Active Directory.
get_zone_nss_vars

Syntax
get_zone_nss_vars

Abbreviation
gznv

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of strings in the form A=B.

Examples
get_zone_nss_vars

returns: NSSRANDCOUNT=32000

NSRANDFILE=/params/nssrand.seed

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone.

Chapter 4 ADEdit command reference

143

Command descriptions

save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

ADEdit Programmers Guide

144

Command descriptions

get_zone_user_field
The get_zone_user_field command returns a field (attribute) value from the currently selected zone user stored in memory.
get_zone_user_field does not query Active Directory for the zone user. If youve changed

field values using ADEdit without saving the zone user to Active Directory, the field value you retrieve using get_zone_user_field wont match the same field value for the zone user stored in Active Directory.

Syntax
get_zone_user_field field

Abbreviation
gzuf

Options
This command takes no options.

Arguments
This command takes the following argument, which is case-sensitive:
Argument field Type string Description Required. The case-sensitive name of the field whose value to retrieve. Fields are standard etc/passwd fields for a user account. Possible values are: uname: the username uid: the user ID gid: the group ID gecos: user account information home: users home directory shell: users shell type enabled: whether user is enabled or not. 1 is enabled, 0 is disabled. Note that this field is only available for users in a classic zone. All other zone types use roles instead of enabled/disabled. createTime: the time and date this zone user was created, returned in generalized time format modifyTime: the time and date this zone user was created, returned in generalized time format dn: the zone users distinguished name. (Note: if the user is in an SFU zone, no value is returned for this field.)

Return value
This command returns a field value, which varies in type depending on the data type stored by the field.

Chapter 4 ADEdit command reference

145

Command descriptions

Examples
get_zone_user_field uname

returns: adam

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user. get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. set_zone_user_field sets a field value in the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

ADEdit Programmers Guide

146

Command descriptions

get_zone_users
The get_zone_users command checks Active Directory and returns a Tcl list of zone users defined within the currently selected zone. If executed in a script, this command does not output its list to stdout, and no output appears in the shell where the script is executed. Use list_zone_users to output to stdout.

Syntax
get_zone_users

Abbreviation
gzu

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of zone users defined in the currently selected zone. Each entry in the list is the user principal name (UPN) of a user that you can use to look up that user. If a zone user is an orphan user (its corresponding AD user no longer exists), the user is listed by its security identifier (SID) instead of a UPN.

Examples
get_zone_users

returns: [email protected]

[email protected] [email protected]

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user. set_zone_user_field sets a field value in the currently selected zone user.

Chapter 4 ADEdit command reference

147

Command descriptions

save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

ADEdit Programmers Guide

148

Command descriptions

get_zones
The get_zones command checks Active Directory and returns a Tcl list of zones within a specified domain. Note that this does not include computer zones or computer roles.

Syntax
get_zones domain

Abbreviation
gz

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument domain Type string Description Required. The name of the domain for which to return zones.

Return value
This command returns a Tcl list of DNs of the zones in the specified domain.

Examples
get_zones acme.com

returns: {CN=default,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} {CN=cz1,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} {CN=cz2,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} {CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com}

Related commands

create_zone creates a new zone in Active Directory. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone.

Chapter 4 ADEdit command reference

149

Command descriptions

save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

ADEdit Programmers Guide

150

Command descriptions

getent_passwd
The getent_passwd command returns a Tcl list of entries in the ADEdit host machines etc/passwd filein other words, a list of locally visible UNIX users.

Syntax
getent_passwd

Abbreviation
gep

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a Tcl list of passwd file entries. Each element in the list is a file entry, and includes the username and all passwd data associated with that username.

Examples
getent_passwd

returns:
{root x 0 0 root /root /bin/bash} {bin x 1 1 bin /bin /sbin/nologin} {daemon x 2 2 daemon /sbin /sbin/nologin} {adm x 3 4 adm /var/adm /sbin/nologin} {lp x 4 7 lp /var/spool/lpd /sbin/nologin} {sync x 5 0 sync /sbin /bin/sync} {shutdown x 6 0 shutdown /sbin /sbin/shutdown}

and many more entries.

Related commands

get_pwnam searches the etc/passwd file for a UNIX username and, if found, returns a Tcl list of the passwd profile values associated with the user.

Chapter 4 ADEdit command reference

151

Command descriptions

help
The help command returns detailed information about one or more ADEdit commands. Its followed by a command pattern that is either the name of a single ADEdit command or a string with wildcards that specifies multiple possible commands. The command pattern may also be a command abbreviation. The command pattern wildcards are: ? for a single character

for multiple characters

Syntax
help command_pattern

Abbreviation
h

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument command_pattern Type string Description Required. The name of one or more ADEdit commands for which to return information. The name may use ? and * wildcards to specify a single character or multiple characters respectively. The name may also be a command shortcut.

Return value
This command returns detailed information for the specified command or commands. If command_pattern matches nothing, this command returns nothing.

Examples
help explain_sd

returns detailed information for the explain_sd command.

help ?et*

returns detailed information for get_zones, get_zone_field, set_zone_field, get_role_field, set_role_field, and the many other ADEdit commands that start with get or set.

ADEdit Programmers Guide

152

Command descriptions

Related commands
None.

Chapter 4 ADEdit command reference

153

Command descriptions

joined_get_user_membership
The joined_get_user_membership command uses adclient to query Active Directory. It asks for a list of groups that a user belongs to in the domain to which ADEdits host computer is joined. If the adclient query returns groups, this command returns those groups in a Tcl list. Note that because this command queries Active Directory through adclient, the query may go to adclients cache and not directly to AD. The adclient cache isnt guaranteed to be updated with ADedit activity. Therefore you may need to execute the Centrify UNIX CLI command adflush just before using joined_get_user_membership to ensure you get the most up-to-date results.

Syntax
joined_get_user_membership user_UPN

Abbreviation
jgum

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument user_UPN Type string Description Required. The user principal name (UPN) of the user to check for group membership.

Return value
This command returns a Tcl list of groups.

Examples
joined_get_user_membership [email protected]

returns:
acme.com/Users/Domain Users

Related commands

joined_user_in_group checks AD to see if a user is in a group. get_group_members returns a Tcl list of members in a group.

ADEdit Programmers Guide

154

Command descriptions

joined_name_to_principal
The joined_name_to_principal command uses adclient to query Active Directory for a UNIX name of a user and, if found, returns the user principal name (UPN) of the user associated with the UNIX name. This command works only for users within the domain to which ADEdits host computer is joined through adclient.

Syntax
joined_name_to_principal UNIX_name

Abbreviation
jntp

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument UNIX_name Type string Description Required. The UNIX name of a user to look for in AD.

Return value
This command returns the UPN of the user if found in AD.

Examples
joined_name_to_principal adam

returns [email protected]

Related commands

principal_to_dn searches Active Directory for a user principal name (UPN) and, if found, returns the corresponding DN. dn_to_principal searches Active Directory for a DN and, if found, returns the corresponding UPN. principal_from_sid searches Active Directory for an SID and returns the security principal associated with the SID.

Chapter 4 ADEdit command reference

155

Command descriptions

joined_user_in_group
The joined_user_in_group command uses adclient to query Active Directory to see if a user belongs to a group. This command works only for users and groups within the domain to which ADEdits host computer is joined through adclient. Note that because this command queries Active Directory through adclient, the query may go to adclients cache and not directly to AD. The adclient cache isnt guaranteed to be updated with ADedit activity. Therefore you may need to execute the Centrify UNIX CLI command adflush just before using joined_user_in_group to ensure you get the most up-to-date results.

Syntax
joined_user_in_group user_UPN group_UPN

Abbreviation
jug

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument user_UPN group_UPN Type string string Description Required. The user principal name (UPN) of the user to check for group membership. Required. The UPN of the group to check for user membership.

Return value
This command returns 1 if the user is a member of the group, 0 if the user is not a member of the group.

Examples
joined_user_in_group [email protected] [email protected]

returns 1, which means that Martin Moore is a member of the poweradmins group.

Related commands

get_group_members returns a Tcl list of members in a group. joined_get_user_membership returns a Tcl list of groups that a user belongs to.

ADEdit Programmers Guide

156

Command descriptions

list_dz_commands
The list_dz_commands command checks Active Directory (AD) and returns a list of DirectAuthorize (DZ) command objects defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_dz_commands to return a Tcl list. Note that list_dz_commands only returns DZ command data for classic4 and tree zones.

Syntax
list_dz_commands

Abbreviation
lsdzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of DZ commands defined in the currently selected zone. Each entry in the list contains these fields, each separated from the next by a colon (:): The name of the DZ command followed by a slash (?) and the name of the zone where the DZ command is defined.

The properties of the DZ command. Text describing the DZ command.

Examples
list_dz_commands

returns:
root_any/global : * form(0) dzdo_runas(root) flags(16) : Run any command as root

Related commands

get_dz_commands returns a Tcl list of DZ commands in the current zone.

Chapter 4 ADEdit command reference

157

Command descriptions

new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory. delete_dz_command deletes the selected DZ command from Active Directory and from memory.

ADEdit Programmers Guide

158

Command descriptions

list_nis_map
The list_nis_map command returns a list of all entries within the currently selected NIS map. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_nis_map to return a Tcl list of NIS map entries.

Syntax
list_nis_map

Abbreviation
lsnm

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of the entries within the currently selected NIS map. Each entry in the list contains: The key

The instance number of the key (there may be multiple entries with the same key) The value

Each entry component is separated from the next by a colon (:).

Examples
list_nis_map

returns:
Argo:1: tweety.acme.com

Buster:1: bigbird.acme.com

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map.

Chapter 4 ADEdit command reference

159

Command descriptions

select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

160

Command descriptions

list_nis_maps
The list_nis_maps command checks Active Directory (AD) and returns a list of NIS maps defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_nis_maps to return a Tcl list.

Syntax
list_nis_maps

Abbreviation
lsnms

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of NIS maps defined in the currently selected zone.

Examples
list_nis_maps

returns:
Aliases Printers Services

Related commands

get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map.

Chapter 4 ADEdit command reference

161

Command descriptions

delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

162

Command descriptions

list_pam_apps
The list_pam_apps command checks Active Directory (AD) and returns a list of plug-in authentication module (PAM) applications defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_pam_apps to return a Tcl list. Note that list_pam_apps only returns PAM application data for classic4 and tree zones.

Syntax
list_pam_apps

Abbreviation
lspa

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of PAM applications defined in the currently selected zone. Each entry contains these fields, each separated from the next by a colon (:): PAM application name followed by a slash (/) and the zone in which the PAM application is defined.

The name of the application (or applications, using wild cards) that may use PAM. Text describing the PAM application object.

Examples
list_pam_apps

returns:

login-all/global : * : Predefined global PAM permission. Do not delete

Related commands

get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application.

Chapter 4 ADEdit command reference

163

Command descriptions

select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application. set_pam_field sets a field value in the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

ADEdit Programmers Guide

164

Command descriptions

list_role_assignments
The list_role_assignments command checks Active Directory (AD) and returns a list of role assignments defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_role_assignments to return a Tcl list. Note that list_role_assignments only returns role assignment data for classic4 and tree zones.

Syntax
list_role_assignments

Abbreviation
lsra

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of role assignments defined in the currently selected zone. Each entry in the list provides this information: The user principal name (UPN) of the user or group to whom the role assignment applies.

The name of the role assigned followed by a slash (/) and the zone where the role is defined.

Examples
list_role_assignments

returns:
[email protected]: root/global [email protected]: login/global

Related commands

get_role_assignments returns a Tcl list of role assignments in the current zone.

Chapter 4 ADEdit command reference

165

Command descriptions

new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

ADEdit Programmers Guide

166

Command descriptions

list_role_rights
The list_role_rights command returns a list of all commands and PAM applications set within the currently selected role. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script.
list_role_rights

does not query Active Directory for the role. If youve changed commands and PAM applications using ADEdit without saving the role to Active Directory, commands and PAM applications you retrieve using list_role_rights wont match those stored in Active Directory. Note that list_role_rights only returns role rights for classic4 and tree zones.

Syntax
list_role_rights

Abbreviation
lsrr

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of the PAM applications and commands set within the currently selected role. The entry for each application or command lists the application or command name, the attributes of the application or command, and any descriptive text.

Examples
list_role_rights

returns:
login-ll/cz1 : * : Predefined global PAM permission. Do not delete.

ls/cz1 : ls form(0) dzdo_runas(admin) flags(16) ;

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role

Chapter 4 ADEdit command reference

167

Command descriptions

get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

168

Command descriptions

list_roles
The list_roles command checks Active Directory (AD) and returns a list of roles defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_roles to return a Tcl list. Note that list_roles only returns role data for classic4 and tree zones.

Syntax
list_roles

Abbreviation
lsr

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of roles defined in the currently selected zone.

Examples
list_roles

returns:
listed login

Related commands

get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role.

Chapter 4 ADEdit command reference

169

Command descriptions

get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

170

Command descriptions

list_zone_computers
The list_zone_computers command checks Active Directory (AD) and returns a list of zone computers defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_zone_computers to return a Tcl list.

Syntax
list_zone_computers

Abbreviation
lszc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of zone computers defined in the currently selected zone. The entry for each zone computer contains these fields: User principal name (UPN) of the zone computer

Number of CPUs in the computer and the version of adclient present on the computer The domain name system (DNS) name of the computer.

A colon separates each field from the next.

Examples
list_zone_computers

returns: [email protected]:cpus (1) agentVersion (CentrifyDC 5.0.0): printserv.acme.com

Related commands

get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone.

Chapter 4 ADEdit command reference

171

Command descriptions

new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer. save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

ADEdit Programmers Guide

172

Command descriptions

list_zone_groups
The list_zone_groups command checks Active Directory (AD) and returns a list of zone groups defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_zone_groups to return a Tcl list.

Syntax
list_zone_groups

Abbreviation
lszg

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of zone groups defined in the currently selected zone. Each entry in the list contains the user principal name (UPN) of the group (which you can use as a key for retrieval) followed by the field values of each group record. These are standard etc/group fields. A colon separates each field from the next. The entry for each zone group contains: UPN (user principal name) of the zone group as it is stored in AD

UNIX group name GID (group ID)

Examples
list_zone_groups

returns: [email protected]:padmins:24

Related commands

get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group.

Chapter 4 ADEdit command reference

173

Command descriptions

select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

ADEdit Programmers Guide

174

Command descriptions

list_zone_users
The list_zone_users command checks Active Directory (AD) and returns a list of zone users defined within the currently selected zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use get_zone_users to return a Tcl list.

Syntax
list_zone_users

Abbreviation
lszu

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns a list to stdout of zone users defined in the currently selected zone. Each entry in the list usually contains the user principal name (UPN) of the user (which you can use as a key for retrieval) followed by the field values of each user record. These are standard etc/passwd fields. A colon separates each field from the next. The entry for each zone user contains: UPN (user principal name) of the zone user as it is stored in AD. If a zone user is an orphan user (its corresponding AD user no longer exists), the security identifier (SID) of the orphan user.

UNIX username UID (user ID) GID (group ID) GECOS datathe zone userss personal information The home directory The users shell type Whether the user is enabled or disabled (in classic zones only)

Chapter 4 ADEdit command reference

175

Command descriptions

Examples
list_zone_users

returns: [email protected]:adam:10001:10001:%{u:samaccountname}:%{home}/ %{user}:%{shell}:

[email protected]:brenda:10002:10002:%{u:samaccountname}:%{home}/ %{user}:%{shell}: [email protected]:chris:10003:10003:%{u:samaccountname}:%{home}/ %{user}:%{shell}:

Related commands

get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user. set_zone_user_field sets a field value in the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

ADEdit Programmers Guide

176

Command descriptions

new_dz_command
The new_dz_command command creates a new DirectAuthorize (DZ) command object for the current zone and sets the new DZ command as the currently selected DZ command in memory. The new DZ command has no field values set. does not save the new DZ command to Active Directory (AD). To do so, you must first set at least the command field of the new DZ command using set_dzc_field and then use save_dz_command. If you dont save a new DZ command, it will disappear when you select a new DZ command or when the ADEdit session ends.
new_dz_command new_dz_command

can only create a DZ command when a tree zone is the selected zone. The command will not work in other zone types.

Syntax
new_dz_command name

Abbreviation
newdzc

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument name Type string Description Required. The name to assign to the new DZ command.

Return value
This command returns nothing if successful.

Examples
new_dz_command account_manager

creates a new DZ command account_manager in the current zone.

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. get_dz_commands returns a Tcl list of DZ commands in the current zone.

Chapter 4 ADEdit command reference

177

Command descriptions

select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory. delete_dz_command deletes the selected DZ command from Active Directory and from memory.

ADEdit Programmers Guide

178

Command descriptions

new_nis_map
The new_nis_map command creates a new NIS map for the current zone and sets the new NIS map as the currently selected NIS map in memory. The new NIS map has no map entries.
new_nis_map does not save the new NIS map to Active Directory (AD). To do so, you must use save_nis_map. If you dont save a new NIS map, it will disappear when you select a new NIS map or when the ADEdit session ends.

Syntax
new_nis_map map

Abbreviation
newnm

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument map Type string Description Required. The name of the new NIS map

Return value
This command returns nothing if successful.

Examples
new_nis_map Printers

creates a new NIS map printers in the current zone.

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map.

Chapter 4 ADEdit command reference

179

Command descriptions

add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

ADEdit Programmers Guide

180

Command descriptions

new_object
The new_object command creates a new Active Directory (AD) object and sets the new object as the currently selected AD object in memory. The new object has no field values set.
new_object

does not save the new object to Active Directory (AD). To do so, you must use

save_object. If you dont save a new object, it will disappear when you select a new object

or when the ADEdit session ends.

new_object does not check to see if your new object conforms to ADs expectations for the

new object in the location you specify. AD will report any errors when you try to save the object.

Syntax
new_object dn

Abbreviation
newo

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument dn Type Description

distin- Required. The DN for the new object. guished name (DN)

Return value
This command returns nothing if successful.

Examples
new_object ou=acme,cn=Program Data,dc=acme,dc=com

creates a new container acme in the container Program Data in acme.com and stores it in memory as the currently selected AD object.

Chapter 4 ADEdit command reference

181

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

182

Command descriptions

new_pam_app
The new_pam_app command creates a new plug-in authentication module (PAM) application object for the current zone and sets the new PAM application as the currently selected PAM application in memory. The new PAM application has no field values set. does not save the new PAM application to Active Directory (AD). To do so, you must first set at least the application field of the new PAM application using set_pam_field and then use save_pam_app. If you dont save a new PAM application, it will disappear when you select a new PAM application or when the ADEdit session ends.
new_pam_app new_pam_app

can only create a PAM application when a tree zone is the selected zone. The command will not work in other zone types.

Syntax
new_pam_app name

Abbreviation
newpam

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument name Type string Description Required. The name to assign to the new PAM application object.

Return value
This command returns nothing if successful.

Examples
new_pam_app basic

creates a new PAM application basic in the current zone.

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. get_pam_apps returns a Tcl list of PAM applications in the current zone.

Chapter 4 ADEdit command reference

183

Command descriptions

select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application. set_pam_field sets a field value in the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

ADEdit Programmers Guide

184

Command descriptions

new_role
The new_role command creates a new role for the current zone and sets the new role as the currently selected role in memory. The new role has no field values set. does not save the new role to Active Directory (AD). To do so, you must use save_role. If you dont save a new role, it will disappear when you select a new role or when the ADEdit session ends.
new_role new_role

can only create a role when a tree zone is the selected zone. The command will not work in other zone types.

Syntax
new_role name

Abbreviation
newr

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument name Type string Description Required. The name to assign to the new role.

Return value
This command returns nothing if successful.

Examples
new_role customerservice

creates a new role customerservice in the current zone.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. select_role retrieves a role from Active Directory and stores it in memory as the selected role.

Chapter 4 ADEdit command reference

185

Command descriptions

get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

186

Command descriptions

new_role_assignment
The new_role_assignment command creates a new role assignment for the current zone and sets the new role assignment as the currently selected role assignment in memory. The new role assignment has no field values set. does not save the new role assignment to Active Directory (AD). To do so, you must first set at least the role field of the new role assignment using set_role_assignment_field and then use save_role_assignment. If you dont save a new role assignment, it will disappear when you select a new role assignment or when the ADEdit session ends.
new_role_assignment new_role_assignment

can only create a role assignment when a tree zone is the selected zone. The command will not work in other zone types.

Syntax
new_role_assignment upn

Abbreviation
newra

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument upn Type string Description Required. The user principal name (UPN) of the user or group to assign the role to.

Return value
This command returns nothing if successful.

Examples
new_role_assignment [email protected]

creates a new role assignment for [email protected] in the current zone. The role assignments fields must be set to specify a role and a time interval for the role.

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment.

Chapter 4 ADEdit command reference

187

Command descriptions

get_role_assignments returns a Tcl list of role assignments in the current zone. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

ADEdit Programmers Guide

188

Command descriptions

new_zone_computer
The new_zone_computer command creates a new zone computer for the current zone and sets the new zone computer as the currently selected zone computer in memory. The new zone computer has no field values set. not save the new zone computer to Active Directory (AD). To do so, you must use save_zone_computer. If you dont save a new zone computer, it will disappear when you select a new zone computer or when the ADEdit session ends.
new_zone_computer new_zone_computer does

does not work if it cant find the supplied AD computer in AD.

Syntax
new_zone_computer sAMAccountName@domain

Abbreviation
newzc

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument sAMAccountName @domain Type string Description Required. The sAMAccountName of an AD computer followed by @ and the domain name where the computer is located. (The sAMAccountName is found in ADUC as Computer Name (pre-Windows 2000). Its also returned by get_zone_computers.)

Return value
This command returns nothing if successful.

Examples
new_zone_computer [email protected]

creates a new zone computer [email protected] in the current zone. Note that Tcl syntax requires $@ to represent a literal @. The argument may also be presented surrounded by braces: {[email protected]}.

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer.

Chapter 4 ADEdit command reference

189

Command descriptions

get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer. save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

ADEdit Programmers Guide

190

Command descriptions

new_zone_group
The new_zone_group command creates a new zone group for the current zone that is based on an existing AD group. The command sets the new zone group as the currently selected zone group in memory. The new zone group has no field values set.
new_zone_group does not save the new zone group to Active Directory (AD). To do so, you

must first set at least one field of the new zone group using set_zone_group_field and then use save_zone_group. (If the selected zone is a classic, zone, you must set all fields.) If you dont save a new zone group, it will disappear when you select a new zone group or when the ADEdit session ends.
new_zone_group does not work if it cant find the

supplied AD group in AD. The command will search for the group first by the supplied UPN in the specified domain, then by the sAMAccountname in the specified domain, then by the supplied UPN in any bound domain.

Syntax
new_zone_group AD_group_UPN

Abbreviation
newzg

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument AD_group_UPN Type string Description Required. The user principal name (UPN) of an AD group.

Return value
This command returns nothing if successful.

Examples
new_zone_group [email protected]

creates a new zone group [email protected] in the current zone.

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group.

Chapter 4 ADEdit command reference

191

Command descriptions

get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

ADEdit Programmers Guide

192

Command descriptions

new_zone_user
The new_zone_user command creates a new zone user for the current zone and sets the new zone user as the currently selected zone user in memory. The new zone user has no field values set. does not save the new zone user to Active Directory (AD). To do so, you must first set at least one field of the new zone user using set_zone_user_field and then use save_zone_user. (If the selected zone is a classic, zone, you must set all fields.) If you dont save a new zone user, it will disappear when you select a new zone user or when the ADEdit session ends.
new_zone_user

Each new zone user is created on an AD user. You can create more than one zone user within a zone on a single AD user. The first zone user you create uses the AD users user principal name (UPN): [email protected], for example. Any other zone users you create on the same AD user must use aliases. An alias is the AD users UPN with +n appended where n is a positive integer that is unique for this AD user in this zone. [email protected]+1 is an alias, for example, as is [email protected]+5. Alias integers need not be consecutive or in order. (Note that SFU zones do not support user aliases.)
new_zone_user

does not work if it cant find the supplied AD user in AD. The command will search for the user first by the supplied UPN in the specified domain, then by the sAMAccountname in the specified domain, then by the supplied UPN in any bound domain.

Syntax
new_zone_user AD_user_UPN

Abbreviation
newzu

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument AD_user_UPN Type string Description Required. The user principal name (UPN) of an AD user. If this is an alias, the UPN with an appended + followed by a positive integer that is unique for this user and this zone.

Return value
This command returns nothing if successful.

Chapter 4 ADEdit command reference

193

Command descriptions

Examples
new_zone_user [email protected]

creates a new zone user [email protected] in the current zone.

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user. get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user. set_zone_user_field sets a field value in the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

ADEdit Programmers Guide

194

Command descriptions

pop
The pop command retrieves a previously stored context (bindings and selected objects) from the top of the context stack and replaces ADEdits current context with the retrieved context. Popping a context from the context stack removes the context from the stack. This command is useful for Tcl scripts that use subroutines. A push can save the context before its altered in the subroutine; a pop can return the saved context when the subroutine returns.

Syntax
pop

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful. If the stack is empty, it returns a message stating so.

Examples
pop

retrieves the context from the top of the context stack and uses it as the current ADEdit context.

Related commands
These commands perform actions related to this command: show returns the current context of ADEdit: its bound domains and its currently selected objects.

push saves ADEdits current context to ADEdits context stack.

Chapter 4 ADEdit command reference

195

Command descriptions

principal_from_sid
The principal_from_sid command takes the security identifier (SID) of a security principal in Active Directory. It looks up that principal and, if found, returns the Active Directory name of the principal.

Syntax
principal_from_sid sid

Abbreviation
pfs

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument sid Type string Description Required. The security identifier of an Active Directory security principal.

Return value
This command returns the Active Directory name of the principal if it finds a principal. If it does not find a principal, it returns a message stating so.

Examples
principal_from_sid S-1-5-21-2076040321-3326545908-468068287-1159

returns: [email protected]

Related commands

principal_to_dn searches Active Directory for a user principal name (UPN) and, if found, returns the corresponding distinguished name (DN). dn_to_principal searches Active Directory for a distinguished name (DN) and, if found, returns the corresponding user principal name (UPN).

ADEdit Programmers Guide

196

Command descriptions

principal_to_dn
The principal_to_dn command takes the user principal name (UPN) of a security principal (user, machine, or group), searches Active Directory for the UPN, and if it finds a security principal under the UPN returns the distinguished name (DN) of the principal.

Syntax
principal_to_dn principal_upn

Abbreviation
ptd

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument principal_upn Type string Description Required. The user principal name (UPN) of a security principal.

Return value
This command returns a distinguished name. If the command doesnt find the specified security principal in Active Directory, it presents a message that it didnt find the principal.

Examples
principal_to_dn [email protected]

returns: cn=brenda

butler,cn=users,dc=acme,dc=com

Related commands

dn_from_domain converts a domains dotted name to a distinguished name. get_parent_dn returns the parent of an LDAP path (a distinguished name): it removes the first element of the DN and returns the rest. get_rdn returns the relative distinguished name (DN) of an LDAP path: it returns only the fist element of the supplied DN. dn_to_principal searches Active Directory for a distinguished name (DN) and, if found, returns the corresponding user principal name (UPN).

Chapter 4 ADEdit command reference

197

Command descriptions

principal_from_sid searches Active Directory for an SID and returns the security principal associated with the SID.

ADEdit Programmers Guide

198

Command descriptions

push
The push command saves ADEdits current contextits bindings and selected objects in memoryto a context stack. It leaves the current context in place, so all current bindings and selected objects remain in effect in ADEdit after the push. This command is useful for Tcl scripts that use subroutines. A push can save the context before its altered in the subroutine; a pop can return the saved context when the subroutine returns.

Syntax
push

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing.

Examples
push

saves the current ADEdit context.

Related commands
These commands perform actions related to this command: show returns the current context of ADEdit: its bound domains and its currently selected objects.

pop restores the context from the top of ADEdits context stack to ADEdit.

Chapter 4 ADEdit command reference

199

Command descriptions

quit
The quit command quits ADEdit and returns to the shell from which ADEdit was launched. Pressing Ctrl-D in ADEdits interactive mode does the same thing, as does entering exit.

Syntax
quit

Abbreviation
q

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing.

Examples
quit

quits ADEdit.

Related commands
None.

ADEdit Programmers Guide

200

Command descriptions

remove_command_from_role
The remove_command_from_role command removes a DirectAuthorize (DZ) command from the currently selected role stored in memory.
remove_command_from_role

does not change the role as it is stored Active Directory; it changes the role only in memory. You must save the role before the removed command takes effect in AD. If you select another role or quit ADEdit before saving the role, any DZ commands youve removed since the last save wont take effect.

remove_command_from_role

will only work if a tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
remove_command_from_role command[/zonename]

Abbreviation
rcfr

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument Type Description Required. The name of a DZ command to remove from the currently selected role followed by an optional slash (/) and the zone name where the DZ command is defined. Distinguishes between two DZ commands with the same name but defined in different zones.

command[/zonename] string

Return value
This command returns nothing if successful.

Examples
remove_command_from_role basicshell/global

removes the DZ command basicshell, defined in the global zone, from the currently selected role.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role

Chapter 4 ADEdit command reference

201

Command descriptions

get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

202

Command descriptions

remove_object_value
The remove_object_value command removes a value from a multi-valued field (attribute) of a specified Active Directory (AD) object in Active Directory. It works only on the object in AD, not on the currently selected AD object in memory (if there is one). If the removed value isnt valid, AD will report an error and remove_object_value wont remove the value. This command is useful for fields that may be very largemembers of a group, for example.

Syntax
remove_object_value dn field value

Abbreviation
rov

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument dn field Type string string Description Required. The distinguished name (DN) of the AD object from which to remove a value. Required. The name of a multi-valued field in the currently selected AD object from which to remove the value. This can be any field that is valid for the type of the currently selected AD object. Required. The value to remove from the field. The type of value depends on the field specified by field.

value

string

Return value
This command returns nothing if successful.

Examples
remove_object_value cn=groups,dc=acme,dc=com users adam.avery

removes the value adam.avery from the users field of the currently selected AD object.

Chapter 4 ADEdit command reference

203

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

204

Command descriptions

remove_pamapp_from_role
The remove_pamapp_from_role command removes a plug-in authentication module (PAM) application from the currently selected role stored in memory. does not change the role as it is stored Active Directory; it changes the role only in memory. You must save the role before the removed PAM application takes effect in AD. If you select another role or quit ADEdit before saving the role, any PAM applications youve removed since the last save wont take effect.
remove_pamapp_from_role

will only work if a tree zone is the currently selected zone. It will not work in other types of zones.
remove_pamapp_from_role

Syntax
remove_pamapp_from_role app[/zonename]

Abbreviation
rpamfr

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument app[/zonename] Type string Description Required. The name of a PAM application to remove from the currently selected role followed by an optional slash (/) and the zone name where the PAM application is defined. The optional zone distinguishes between two PAM applications with the same name but defined in different zones.

Return value
This command returns nothing if successful.

Examples
remove_pamapp_from_role login-all

removes the PAM application login-all, defined in the currently selected zone, from the currently selected role.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role

Chapter 4 ADEdit command reference

205

Command descriptions

get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

206

Command descriptions

remove_sd_ace
The remove_sd_ace command removes an access control entry (ACE) in ACE string form from a security descriptor (SD) in SDDL (security descriptor description language) form. The command looks for the supplied ACE string within the supplied SDDL string. If the command finds the ACE string, it removes it from the SDDL string and returns the SDDL string.

Syntax
remove_sd_ace sddl_string ace_string

Abbreviation
rsa

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument sddl_string ace_string Type string string Description Required. A security descriptor in SDDL format. Required. An access control entry in ACE string form (which is always enclosed in parentheses)

Return value
This command returns an SD in SDDL format if successful.

Examples
This example removes the first ACE string from an SDDL. The ACE string to remove is at the end of the command:
remove_sd_ace

O:DAG:DAD:AI(A;;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;SY)(A;;RCWDWOC CDCLCSWRPWPLOCR;;;DA)(OA;;CCDC;bf967aba-0de6-11d0-a28500aa003049e2;;AO)(OA;;CCDC;bf967a9c-0de6-11d0-a28500aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c16420020c0-11d0-a768-00aa006e0529;bf967aba-0de6-11d0-a285-

Chapter 4 ADEdit command reference

207

Command descriptions

00aa003049e2;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-902000c04fc2d4cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-9020-00c04fc2d4cf;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f4279a2-11d0-9020-00c04fc2d3cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b42200a0c968f939;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a86-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967a9c0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e00a0c983f608;bf967aba-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;L C;;;RU)(A;CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA) (A;;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;SY) returns:

O:DAG:DAD:AI(A;;RCWDWOCCDCLCSWRPWPLOCR;;;DA)(OA;;CCDC;bf967aba-0de6-11d0a285-00aa003049e2;;AO)(OA;;CCDC;bf967a9c-0de6-11d0-a28500aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c16420020c0-11d0-a768-00aa006e0529;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-902000c04fc2d4cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-9020-00c04fc2d4cf;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f4279a2-11d0-9020-00c04fc2d3cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b42200a0c968f939;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a86-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967a9c0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e00a0c983f608;bf967aba-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557-

ADEdit Programmers Guide

208

Command descriptions

d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;LC;;;RU)(A; CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA) (A;;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;SY)

Related commands

explain_sd converts an SD in SDDL format to a human-readable form. add_sd_ace adds an access control entry to an SD. set_sd_owner sets the owner of an SD.

Chapter 4 ADEdit command reference

209

Command descriptions

save_dz_command
The save_dz_command command saves the currently selected (DirectAuthorize) DZ command object in memory to Active Directory. Any ADEdit changes to a selected DZ command wont appear in Active Directory until the DZ command is saved. You must save a DZ command for any changes to take effect. Any changes since the last save to a selected DZ command are lost when ADEdit exits or when you select another DZ command.

Syntax
save_dz_command

Abbreviation
svdzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_dz_command

saves the currently selected DZ command to Active Directory.

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. get_dz_commands returns a Tcl list of DZ commands in the current zone. new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command.

ADEdit Programmers Guide

210

Command descriptions

delete_dz_command deletes the selected DZ command from Active Directory and from memory.

Chapter 4 ADEdit command reference

211

Command descriptions

save_nis_map
The save_nis_map command saves the currently selected NIS map in memory to Active Directory. Any ADEdit changes to a selected NIS map wont appear in Active Directory until the NIS map is saved. You must save a NIS map for any changes to take effect. Any changes since the last save to a selected NIS map are lost when ADEdit exits or when you select another NIS map.

Syntax
save_nis_map

Abbreviation
svnm

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_nis_map

saves the currently selected NIS map to Active Directory.

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone. new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. select_nis_map retrieves a NIS map from Active Directory and stores it in memory as the selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map.

ADEdit Programmers Guide

212

Command descriptions

add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

Chapter 4 ADEdit command reference

213

Command descriptions

save_object
The save_object command saves the currently selected Active Directory (AD) object in memory to Active Directory. Any ADEdit changes to a selected object wont appear in Active Directory until the object is saved. You must save a object for any changes to take effect. Any changes since the last save to a selected object are lost when ADEdit exits or when you select another object. If an object has invalid attributes or values or is the wrong class for the container where its being saved, AD will report an error and the save wont work.

Syntax
save_object

Abbreviation
svo

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_object

saves the currently selected AD object to Active Directory.

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object.

ADEdit Programmers Guide

214

Command descriptions

set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

Chapter 4 ADEdit command reference

215

Command descriptions

save_pam_app
The save_pam_app command saves the currently selected plug-in authentication module (PAM) application object in memory to Active Directory. Any ADEdit changes to a selected PAM application wont appear in Active Directory until the PAM application is saved. You must save a PAM application for any changes to take effect. Any changes since the last save to a selected PAM application are lost when ADEdit exits or when you select another PAM application.

Syntax
save_pam_app

Abbreviation
svpam

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_pam_app

saves the currently selected PAM application to Active Directory.

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application.

ADEdit Programmers Guide

216

Command descriptions

set_pam_field sets a field value in the currently selected PAM application. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

Chapter 4 ADEdit command reference

217

Command descriptions

save_role
The save_role command saves the currently selected role in memory to Active Directory. Any ADEdit changes to a selected role wont appear in Active Directory until the role is saved. You must save a role for any changes to take effect. Any changes since the last save to a selected role are lost when ADEdit exits or when you select another role.

Syntax
save_role

Abbreviation
svr

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_role

saves the currently selected role to Active Directory.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role.

ADEdit Programmers Guide

218

Command descriptions

list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. delete_role deletes the selected role from Active Directory and from memory.

Chapter 4 ADEdit command reference

219

Command descriptions

save_role_assignment
The save_role_assignment command saves the currently selected role assignment in memory to Active Directory. Any ADEdit changes to a selected role assignment wont appear in Active Directory until the role assignment is saved. You must save a role assignment for any changes to take effect. Any changes since the last save to a selected role assignment are lost when ADEdit exits or when you select another role assignment.

Syntax
save_role_assignment

Abbreviation
svra

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_role_assignment

saves the currently selected role assignment to Active Directory.

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment. get_role_assignments returns a Tcl list of role assignments in the current zone. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment.

ADEdit Programmers Guide

220

Command descriptions

set_role_assignment_field sets a field value in the currently selected role assignment. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

Chapter 4 ADEdit command reference

221

Command descriptions

save_zone
The save_zone command saves the currently selected zone in memory to Active Directory. Any changes to the fields of a selected zone wont appear in Active Directory until the zone is saved. You must save a zone or for any changes to take effect. Any changes to a selected zone since the last save are lost when ADEdit exits or when you select another zone. This commands does not save any users added to a zone, just the fields in the currently selected zone. Users must be saved individually.

Syntax
save_zone

Abbreviation
svz

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_zone

saves the currently selected zone or computer role to Active Directory.

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone.

ADEdit Programmers Guide

222

Command descriptions

get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

Chapter 4 ADEdit command reference

223

Command descriptions

save_zone_computer
The save_zone_computer command saves the currently selected zone computer in memory to Active Directory. You must have at least one field value set before you can save a zone computer. In a classic zone, you must have all field values set before you can save a zone computer. Any changes to the fields of a selected zone computer wont appear in Active Directory until the zone computer is saved. You must save a zone computer for any changes to take effect. Any changes to a selected zone computer since the last save are lost when ADEdit exits or when you select another zone computer.

Syntax
save_zone_computer

Abbreviation
svzc

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_zone_computer

saves the currently selected zone computer to Active Directory.

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer. get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer.

ADEdit Programmers Guide

224

Command descriptions

select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

Chapter 4 ADEdit command reference

225

Command descriptions

save_zone_group
The save_zone_group command saves the currently selected zone group in memory to Active Directory. You must have at least one field value set before you can save a zone group. In a classic zone, you must have all field values set before you can save a zone group. Any changes to the fields of a selected zone group wont appear in Active Directory until the zone group is saved. You must save a zone group for any changes to take effect. Any changes to a selected zone group since the last save are lost when ADEdit exits or when you select another zone group.

Syntax
save_zone_group

Abbreviation
svzg

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_zone_group

saves the currently selected zone group to Active Directory.

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group. get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group.

ADEdit Programmers Guide

226

Command descriptions

get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group. delete_zone_group deletes the selected zone group from Active Directory and from memory.

Chapter 4 ADEdit command reference

227

Command descriptions

save_zone_user
The save_zone_user command saves the currently selected zone user in memory to Active Directory. You must have at least one field value set before you can save a zone user. In a classic zone, you must have all field values set before you can save a zone user. Any changes to the fields of a selected zone user wont appear in Active Directory until the zone user is saved. You must save a zone user for any changes to take effect. Any changes to a selected zone user since the last save are lost when ADEdit exits or when you select another zone user.

Syntax
save_zone_user

Abbreviation
svzu

Options
This command takes no options.

Arguments
This command takes no arguments.

Return value
This command returns nothing if successful.

Examples
save_zone_user

saves the currently selected zone user to Active Directory.

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user. get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user.

ADEdit Programmers Guide

228

Command descriptions

set_zone_user_field sets a field value in the currently selected zone user. delete_zone_user deletes the selected zone user from Active Directory and from memory.

Chapter 4 ADEdit command reference

229

Command descriptions

select_dz_command
The select_dz_command command retrieves a DirectAuthorize (DZ) command object in the currently selected zone from Active Directory, stores the DZ command in memory, and sets that DZ command as the currently selected DZ command for other ADEdit commands that work using DZ commands. The DZ command remains selected until another DZ command or zone is selected, until the DZ command is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_dzc_field may change settings within the selected DZ command, but not in the DZ command as it is stored in Active Directory. You must issue a save_dz_command command to write the selected DZ commands settings back to Active Directory. If you dont, any changes to the DZ command wont have any effect.
select_dz_command

only selects DZ commands when a classic4 or tree zone is selected. It will not work for other zone types.

Syntax
select_dz_command command

Abbreviation
sldzc

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument command Type string Description Required. The name of the DZ command to select.

Return value
This command returns nothing if successful.

Examples
select_dz_command account_manager

looks for the DZ command object account_manager in the current zone and, if found, selects it as the current DZ command.

ADEdit Programmers Guide

230

Command descriptions

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. get_dz_commands returns a Tcl list of DZ commands in the current zone. new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. set_dzc_field sets a field value in the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory. delete_dz_command deletes the selected DZ command from Active Directory and from memory.

Chapter 4 ADEdit command reference

231

Command descriptions

select_nis_map
The select_nis_map command retrieves a NIS map in the currently selected zone from Active Directory, stores the NIS map in memory, and sets that NIS map as the currently selected NIS map for other ADEdit commands that work using NIS maps. The NIS map remains selected until another NIS map or zone is selected, until the NIS map is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as add_map_entry may change entries within the selected NIS map, but not in the NIS map as it is stored in Active Directory. You must issue a save_nis_map command to write the selected NIS maps entries back to Active Directory. If you dont, any changes to the NIS map wont have any effect.

Syntax
select_nis_map map

Abbreviation
slnm

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument map Type string Description Required. The name of the NIS map to retrieve from Active Directory.

Return value
This command returns nothing if successful.

Examples
select_nis_map Printers

looks for the NIS map Printers in the current zone and, if found, selects it as the current NIS map.

Related commands

list_nis_maps returns a list of all NIS maps in the currently selected zone. get_nis_maps returns a Tcl list of NIS maps in the current zone.

ADEdit Programmers Guide

232

Command descriptions

new_nis_map creates a new NIS map and stores it in memory as the currently selected NIS map. list_nis_map returns a list to stdout of the entries in the currently selected NIS map. get_nis_map returns a Tcl list of the entries in the currently selected NIS map. add_map_entry adds an entry to the currently selected NIS map. delete_map_entry removes an entry from the currently selected NIS map. get_nis_map_field reads a field value from the currently selected NIS map. save_nis_map saves the selected NIS map with its current entries to Active Directory. delete_nis_map deletes the selected NIS map from Active Directory and from memory.

Chapter 4 ADEdit command reference

233

Command descriptions

select_object
The select_object command retrieves the specified Active Directory (AD) object from AD along with its attributes (fields) and stores the object in memory as the currently selected AD object. You can use options to retrieve the rootSDE of the object, to limit the number of attributes to retrieve for the object, or to retrieve attributes not normally returned by AD.

Syntax
select_object [-rootsde] [-attrs a1[,a2,...]] dn

Abbreviation
slo

Options
This command takes the following options:
Option -rootsde -attrs a1[,a2,...] Description Return the rootSDE of the specified object instead of the object. Specify the attributes to retrieve and store in memory as those attributes named by a1, a2, a3, and so on. If not present, ADEdit retrieves all attributes normally returned by AD. This option is useful for limiting the returned attributes or, in some cases, specifying attributes not normally returned by AD.

Arguments
This command takes the following argument:
Argument dn Type Description

distin- Required. The DN of an object stored in Active Directory. guished name (DN)

Return value
This command returns nothing if successful.

Examples
select_object cn=users,dc=acme,dc=com

finds the container object cn=users,dc=acme,dc=com in AD, returns it with all of its attributes, and stores it in memory as the currently selected AD object.

ADEdit Programmers Guide

234

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. set_object_field sets a field (attribute) value in the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

Chapter 4 ADEdit command reference

235

Command descriptions

select_pam_app
The select_pam_app command retrieves a plug-in authentication module (PAM) application object in the currently selected zone from Active Directory, stores the PAM application in memory, and sets that PAM application as the currently selected PAM application for other ADEdit commands that work using PAM applications. The PAM application remains selected until another PAM application or zone is selected, until the PAM application is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_pam_field may change settings within the selected PAM application, but not in the PAM application as it is stored in Active Directory. You must issue a save_pam_app command to write the selected PAM applications settings back to Active Directory. If you dont, any changes to the PAM application wont have any effect. only selects PAM applications when a classic4 or tree zone is selected. It will not work for other zone types.
select_pam_app

Syntax
select_pam_app name

Abbreviation
slpam

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument name Type string Description Required. The name of the PAM application to select.

Return value
This command returns nothing if successful.

Examples
select_pam_app login-all

looks for the PAM application login-all in the current zone and, if found, selects it as the current PAM application.

ADEdit Programmers Guide

236

Command descriptions

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. get_pam_field reads a field value from the currently selected PAM application. set_pam_field sets a field value in the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

Chapter 4 ADEdit command reference

237

Command descriptions

select_role
The select_role command retrieves a role in the currently selected zone from Active Directory, stores the role in memory, and sets that role as the currently selected role for other ADEdit commands that work using roles. The role remains selected until another role or zone is selected, until the role is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_role_field may change settings within the selected role, but not in the role as it is stored in Active Directory. You must issue a save_role command to write the selected roles settings back to Active Directory. If you dont, any changes to the role wont have any effect. only selects roles when a classic4 or tree zone is selected. It will not work for other zone types.
select_role

Syntax
select_role role

Abbreviation
slr

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument role Type string Description Required. The name of the role to select.

Return value
This command returns nothing if successful.

Examples
select_role servicerep

looks for the role servicerep in the current zone and, if found, selects it as the current role.

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role

ADEdit Programmers Guide

238

Command descriptions

get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. get_role_field reads a field value from the currently selected role. set_role_field sets a field value in the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

Chapter 4 ADEdit command reference

239

Command descriptions

select_role_assignment
The select_role_assignment command retrieves a role assignment in the currently selected zone from Active Directory, stores the role assignment in memory, and sets that role assignment as the currently selected role assignment for other ADEdit commands that work using role assignments. The role assignment remains selected until another role assignment or zone is selected, until the role assignment is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_role_assignment_field may change settings within the selected role assignment, but not in the role assignment as it is stored in Active Directory. You must issue a save_role_assignment command to write the selected role assignments settings back to Active Directory. If you dont, any changes to the role assignment wont have any effect.
select_role_assignment

only selects role assignments when a classic4 or tree zone is selected. It will not work for other zone types.

Syntax
select_role_assignment principal/role[/zone]

Abbreviation
slra

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument principal/role[/zone] Type string Description Required. The user principal name (UPN) of the user or group to whom the role is assigned, followed by a slash (/) the the name of the role to assign to the principal, followed by an optional slash and the zone where the role is defined. if the zone isnt specified here, ADEdit assumes the currently selected zone is where the role is defined.

Return value
This command returns nothing if successful.

Examples
select_role_assignment [email protected]/root/global

ADEdit Programmers Guide

240

Command descriptions

looks for the role assignment that assigns the role root defined in the zone global to the principal [email protected]. The principal is a group.

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment. get_role_assignments returns a Tcl list of role assignments in the current zone. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment. set_role_assignment_field sets a field value in the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

Chapter 4 ADEdit command reference

241

Command descriptions

select_zone
The select_zone command retrieves a zone from Active Directory, stores the zone in memory, and sets that zone as the currently selected zone for other ADEdit commands that affect or are affected by zones. The zone remains selected until another zone is selected, until the zone is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_zone_field may change settings within the selected zone, but not in the zone as it is stored in Active Directory. You must issue a save_zone command to write the selected zones settings back to Active Directory. If you dont, any changes to the zone wont have any effect. Note that ADEdit treats computer roles and computer overrides (also known as computer zones in ADEdit) as zones, so select_zone can retrieve a computer role or a computer zone as the currently selected zone. In that case other ADEdit commands that affect or are affected by the currently selected zone use a computer role or computer zone instead of a standard zone. ADEdit cannot select a zone and a computer role or a computer zone at the same timeyou work only select one at a time.

Syntax
select_zone path

Abbreviation
slz

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument path Type string Description Required. A path to the selected zone or computer role. The path format depends on the type of zone selected: A tree, classic3, classic4, or SFU zone path consists of the zones distinguished name. It may be enclosed in braces or quotes if necessary to enable spaces within the distinguished name. A computer role path consists of the host zones distinguished name followed by a slash (/) and the name of the computer zone. It may be enclosed in braces or quotes if necessary to enable spaces within the distinguished name. A computer override path consists of the computer name followed by an ampersand (@) and the distinguished name of the host zone.

ADEdit Programmers Guide

242

Command descriptions

Return value
This command returns nothing if successful.

Examples
select_zone "CN=cz1,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com

selects the zone cz1 in the domain acme.com.

select_zone CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com/ LinuxComputers

selects the computer role LinuxComputers in the host zone global in the domain acme.com.
select_zone server1@CN=cz1,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com

selects the computer zone server1 in the host zone global in the domain acme.com.

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. get_zone_field reads a field value from the currently selected zone. set_zone_field sets a field value in the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory. delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

Chapter 4 ADEdit command reference

243

Command descriptions

select_zone_computer
The select_zone_computer command retrieves a zone computer in the currently selected zone from Active Directory, stores the zone computer in memory, and sets that zone computer as the currently selected zone computer for other ADEdit commands that work using zone computers. The zone computer remains selected until another zone computer or zone is selected, until the zone computer is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_zone_computer_field may change settings within the selected zone computer, but not in the zone computer as it is stored in Active Directory. You must issue a save_zone_computer command to write the selected zone computers settings back to Active Directory. If you dont, any changes to the zone computer wont have any effect.

Syntax
select_zone_computer sAMAccountName@domain

Abbreviation
slzc

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument sAMAccountName@ domain Type string Description Required. The sAMAccountName of an AD computer followed by @ and the domain where the computer is located. (The sAMAccountName is found in ADUC as Computer Name (pre-Windows 2000 . Its also returned by get_zone_computers.)

Return value
This command returns nothing if successful.

Examples
select_zone_computer [email protected]

looks for the zone computer sales2 in the current zone and, if found, selects it as the current zone computer.

ADEdit Programmers Guide

244

Command descriptions

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer. get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. get_zone_computer_field reads a field value from the currently selected zone computer. set_zone_computer_field sets a field value in the currently selected zone computer. save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

Chapter 4 ADEdit command reference

245

Command descriptions

select_zone_group
The select_zone_group command retrieves a zone group in the currently selected zone from Active Directory, stores the zone group in memory, and sets that zone group as the currently selected zone group for other ADEdit commands that work using zone groups. The zone group remains selected until another zone group or zone is selected, until the zone group is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_zone__group_field may change settings within the selected zone group, but not in the zone group as it is stored in Active Directory. You must issue a save_zone_group command to write the selected zone groups settings back to Active Directory. If you dont, any changes to the zone group wont have any effect.

Syntax
select_zone_group AD_group_UPN

Abbreviation
slzg

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument AD_group_UPN Type string Description Required. The user principal name (UPN) of a zone group in the currently selected zone.

Return value
This command returns nothing if successful.

Examples
select_zone_group [email protected]

looks for poweradmins in the current zone and, if found, selects it as the current zone group.

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group.

ADEdit Programmers Guide

246

Command descriptions

get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. get_zone_group_field reads a field value from the currently selected zone group. set_zone_group_field sets a field value in the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

Chapter 4 ADEdit command reference

247

Command descriptions

select_zone_user
The select_zone_user command retrieves a zone user in the currently selected zone from Active Directory, stores the zone user in memory, and sets that zone user as the currently selected zone user for other ADEdit commands that work using zone users. The zone user remains selected until another zone user or zone is selected, until the zone user is deleted, or until the ADEdit session ends. Subsequent ADEdit commands such as set_zone__user_field may change settings within the selected zone user, but not in the zone user as it is stored in Active Directory. You must issue a save_zone_user command to write the selected zone users settings back to Active Directory. If you dont, any changes to the zone user wont have any effect.

Syntax
select_zone_user user

Abbreviation
slzu

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument user Type string Description Required. The user principal name (UPN) of a zone user in the currently selected zone. If the zone user is an orphan user (the corresponding AD user no longer exists), there is no UPN so you must supply the users security identifier (SID) instead of a UPN.

Return value
This command returns nothing if successful.

Examples
select_zone_user [email protected]

looks for adam.avery in the current zone and, if found, selects it as the current zone user.

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user.

ADEdit Programmers Guide

248

Command descriptions

get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. get_zone_user_field reads a field value from the currently selected zone user. set_zone_user_field sets a field value in the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

Chapter 4 ADEdit command reference

249

Command descriptions

set_dzc_field
The set_dzc_field command sets the value for a field (attribute) value in the currently selected DirectAuthorize (DZ) command object stored in memory.
set_dzc_field does not set a field value stored in Active Directory for this DZ command; it

sets only the field in memory. You must save the DZ command before any changed fields take effect in Active Directory. If you select another DZ command or quit ADEdit before saving the DZ command, any field changes youve made since the last save wont take effect. only work if a tree zone is the currently selected zone. It will not work in other types of zones.
set_dzc_field will

Syntax
set_dzc_field field value

Abbreviation
sdzcf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to retrieve. Possible values are: description: text describing the DZ command. cmd: the UNIX command string (or strings) specifying restricted commands. This can be a string that may include wildcards (*, ? and !), or it may be a regular expression. If using wildcards, a ! before a command string specifies not that string. The form field sets whether this string is interpreted as a regular expression or a string that includes wildcards. path: thepath to the commands location. May use wildcards or be a regular expression as described for the cmd field. form: the form of the string used in the cmd and path fields. An integer: 0 is a string that may include wild cards 1 is a regular expression dzdo_runas: a list of users and groups that can run this command under dzdo (DirectAuthorizes version of sudo). Users may be listed by username or user ID (UID). dzsh_runas: a list of users and groups that can run this command under dzsh (DirectAuthorizes restricted environment shell). Users may be listed by username or user ID (UID).

ADEdit Programmers Guide

250

Command descriptions

Argument

Type

Description keep: a comma-separated list of environment variables from the current users environment to keep in addition to the default set of the users environment variables that are retained. (The default keep set is defined in the dzdo.env_keep parameter of centrifydc.conf).)These environment variables are used by the commands specified in cmd. This field has effect only if the flag fields 16 flag is set. del: a comma-separated list of environment variables from the current users environment to delete in addition to the default set of environment variables specified to delete. (The default delete set is defined in the dzdo.env_delete parameter of centrifydc.conf.) These environment variables are used by the commands specified in cmd. This field has effect only if the flag fields 16 flag is not set. add: a comma-separated list of environment variables to add to the final set of environment variables resulting from the keep or delete sets described in the keep and delete fields. pri: the command priority for this DZ command object, used for handling multiple matches for DZ commands specified by wild cards. If commands specified by this DZ command object match commands specified by another DZ command object, the DZ command object with the higher command priority prevails. This field takes an integer value; the higher the number, the higher the priority. umask: the umask value used to define who can execute the command. This is a 3-digit octal value that defines read, write, or execute permission for owner, group, and other. The left digit defines owner execution rights, the middle digit defines group execution rights, the right digit defines other execution rights. Each digit is a combination of binary flags, one flag for each right: 4 is read 2 is write 1 is execute These values add together in a digit to define rights available for the digits entity: for example, a 600(4+2) is both read and write for the owner, but nothing for the group or others.

Chapter 4 ADEdit command reference

251

Command descriptions

Argument

Type

Description flags: specifies different properties of the command. This value is an integer from 0 to 31 that represents a combination of binary flags, one flag for each property: 1 is allow nested command execution (or not if not set) 2 is authentication required with users password (cant be set simultaneously with the 4 flag). If neither 2 nor 4 is set, authentication is not required. 4 is authentication required, run as the targets password (cant be set simultaneously with the 2 flag). If neither 2 nor 4 is set, authentication is not required. 8 is preserve group membership (or dont if not set). 16 is reset environment variables for the command, deleting those variables specified in the dsdo.env_delete parameter of centrifydc.conf, exempting those variables specified in the keep field. If this flag is not set, the command is set to remove the unsafe environment variables specified in the dsdo.env_delete parameter of centrifydc.conf along with any additional environment variables specified by the del field. These values add together to create the flags value. 5, for example, is allow nested command execution and authentication required, run as the targets password (1+4).

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Return value
This command returns nothing if successful.

Examples
set_dzc_field dzdo_runas root

sets the current DZ commands dzdo_runas field to root.

Related commands

list_dz_commands returns a list of all DZ commands in the currently selected zone along with object data for each DZ command. get_dz_commands returns a Tcl list of DZ commands in the current zone. new_dz_command creates a new DZ command and stores it in memory as the currently selected DZ command. select_dz_command retrieves a DZ command from Active Directory and stores it in memory as the selected DZ command. get_dzc_field reads a field value from the currently selected DZ command. save_dz_command saves the selected DZ command with its current settings to Active Directory.

ADEdit Programmers Guide

252

Command descriptions

delete_dz_command deletes the selected DZ command from Active Directory and from memory.

Chapter 4 ADEdit command reference

253

Command descriptions

set_ldap_timeout
The set_ldap_timeout command sets the time-out interval used by LDAP commands. LDAP commands are ADEdit commands such as select_zone that perform read/write operations on Active Directory through a binding. The time-out value controls how long these commands will wait for a response before declaring a time-out and ceasing operation. The default value is five minutes.

Syntax
set_ldap_timeout timeout_in_seconds

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument timeout_in_seconds Type integer Description Required. The number of seconds to wait for a response from Active Directory before declaring a time out. The default value is 300 seconds (5 minutes).

Return value
This command returns nothing if successful.

Examples
set_ldap_timeout 120

sets the LDAP time-out interval to 120 seconds (2 minutes)

Related commands
None.

ADEdit Programmers Guide

254

Command descriptions

set_object_field
The set_object_field command sets the value for a field (attribute) value in the currently selected Active Directory (AD) object stored in memory.
set_object_field

does not set a field value stored in Active Directory for this object; it sets only the field in memory. You must save the object before any changed fields take effect in Active Directory. If you select another object or quit ADEdit before saving the object, any field changes youve made since the last save wont take effect. does not check fields and their values to see if they are valid. When you save an object, AD will check fields and values at that time and report an error if they arent valid.

set_object_field

Syntax
set_object_field field value

Abbreviation
sof

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field value Type string Description Required. The name of the field whose value to set. A field value can by any possible field for the type of object currently selected in memory.

depends Required. The value to assign to the specified field. The value depends on the on field specified field. set_object_field does not check for valid values, so it will accept any value provided. AD will check for valid values when ADEdit saves the object.

Return value
This command returns nothing if successful.

Examples
set_object_field sd $sdvalue

sets the current objects SD field to the string contained in the variable sdvalue (an SDDL string).

Chapter 4 ADEdit command reference

255

Command descriptions

Related commands

get_objects performs an LDAP search of Active Directory and returns a Tcl list of the distinguished names of matching objects. new_object creates a new AD object and stores it in memory as the currently selected AD object. select_object retrieves an object with its attributes from Active Directory and stores it in memory as the selected AD object. get_object_field reads a field (attribute) value from the currently selected AD object. add_object_value adds a value to a multi-valued field attribute of the currently selected AD object. remove_object_value removes a value from a multi-valued field attribute of the currently selected AD object. save_object saves the selected AD object with its current settings to Active Directory. delete_object deletes the selected AD object from Active Directory and from memory. delete_sub_tree deletes an AD object and all of its children from Active Directory.

ADEdit Programmers Guide

256

Command descriptions

set_pam_field
The set_pam_field command sets the value for a field (attribute) value in the currently selected plug-in authentication module (PAM) application object stored in memory.
set_pam_field

does not set a field value stored in Active Directory for this PAM application; it sets only the field in memory. You must save the PAM application before any changed fields take effect in Active Directory. If you select another PAM application or quit ADEdit before saving the PAM application, any field changes youve made since the last save wont take effect.

set_pam_field will only work if a tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
set_pam_field field value

Abbreviation
spf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Possible values are: application: the name of the application allowed to use adclients PAM authentication service. The name can be literal, or it can contain ? or * wildcard characters to specify multiple applications. description: text describing the PAM application

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Return value
This command returns nothing if successful.

Examples
set_pam_field application *

sets the current PAM applications allowable PAM authentication application to all applications. (* is the wildcard for all possible strings.)

Chapter 4 ADEdit command reference

257

Command descriptions

Related commands

list_pam_apps returns a list of all PAM applications in the currently selected zone along with object data for each PAM application. get_pam_apps returns a Tcl list of PAM applications in the current zone. new_pam_app creates a new PAM application and stores it in memory as the currently selected PAM application. select_pam_app retrieves a PAM application from Active Directory and stores it in memory as the selected PAM application. get_pam_field reads a field value from the currently selected PAM application. save_pam_app saves the selected PAM application with its current settings to Active Directory. delete_pam_app deletes the selected PAM application from Active Directory and from memory.

ADEdit Programmers Guide

258

Command descriptions

set_role_assignment_field
The set_role_assignment_field command sets the value for a field (attribute) value in the currently selected role assignment stored in memory.
set_role_assignment_field

does not set a field value stored in Active Directory for this role assignment; it sets only the field in memory. You must save the role assignment before any changed fields take effect in Active Directory. If you select another role assignment or quit ADEdit before saving the role assignment, any field changes youve made since the last save wont take effect.

set_role_assignment_field will only work if a tree zone is the currently selected zone. It will not work in other types of zones.

Syntax
set_role_assignment_field field value

Abbreviation
sraf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Possible values are: role: the name of the role to assign and the zone in which the role was defined. A slash (/) separates the two values. The zone (and accompanying slash) is not required. If the zone is not present, ADEdit assumes the role is defined in the currently selected zone. from: the starting date and time for the role assignment. The date and time is expressed in standard UNIX time. The Tcl clock command manipulates these time values. A value of 0 means no starting date and time for the role assignment. to: the ending date and time for the role assignment. The date and time is expressed in standard UNIX time. The Tcl clock command manipulates these time values. A value of 0 means no ending date and time for the role assignment.

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Chapter 4 ADEdit command reference

259

Command descriptions

Return value
This command returns nothing if successful.

Examples
set_role_assignment_field role root/global

assigns the role root that is defined in the zone global.

Related commands

list_role_assignments returns a list of all role assignments in the currently selected zone along with object data for each role assignment. get_role_assignments returns a Tcl list of role assignments in the current zone. new_role_assignment creates a new role assignment and stores it in memory as the currently selected role assignment. select_role_assignment retrieves a role assignment from Active Directory and stores it in memory as the selected role assignment. get_role_assignment_field reads a field value from the currently selected role assignment. save_role_assignment saves the selected role assignment with its current settings to Active Directory. delete_role_assignment deletes the selected role assignment from Active Directory and from memory.

ADEdit Programmers Guide

260

Command descriptions

set_role_field
The set_role_field command sets the value for a field (attribute) value in the currently selected role stored in memory.
set_role_field

does not set a field value stored in Active Directory for this role; it sets only the field in memory. You must save the role before any changed fields take effect in Active Directory. If you select another role or quit ADEdit before saving the role, any field changes youve made since the last save wont take effect.

will only work if a tree zone is the currently selected zone. It will not work in other types of zones.
set_role_field

Syntax
set_role_field field value

Abbreviation
srf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Possible values are: timebox: the hours in the week when the role is enabled. This value is a 42digit hexadecimal number. When represented in binary, each bit represents an hour of the week as described in the appendix Timebox value format on page 308. sysrights: what system rights are granted to the role. This value is an integer from 0 to 15 that represents a combination of binary flags, one for each right: 1 is the right to password login 2 is the right to SSO login (single sign-on, also known as non-password login) 4 is the right to ignore disabled status in Active Directory and log-on even if the account is disabled in AD. 8 is the right to use a full shell. These values add together to create the sysrights value. 6, for example, is SSO login and ignore disabled (2+4). 15 is all system rights enabled (1+2+4+7). description: text describing the role

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Chapter 4 ADEdit command reference

261

Command descriptions

Return value
This command returns nothing if successful.

Examples
set_role_field sysrights 10

sets the current roles system rights to allow SSO login (2) and to provide a full shell (8).

Related commands

list_roles returns a list of all roles in the currently selected zone along with object data for each role get_roles returns a Tcl list of roles in the current zone. new_role creates a new role and stores it in memory as the currently selected role. select_role retrieves a role from Active Directory and stores it in memory as the selected role. get_role_field reads a field value from the currently selected role. list_role_rights returns a list of all DirectAuthorize (DZ) commands and PAM applications associated with the currently selected role. get_role_commands returns a Tcl list of the (DZ) commands associated with the currently selected role. add_command_to_role adds a DZ command to the currently selected role. remove_command_from_role removes a DZcommand from the currently selected role. get_role_apps returns a Tcl list of the PAM applications associated with the currently selected role. add_pamapp_to_role adds a PAM application to the currently selected role. remove_pamapp_from_role removes a PAM application from the currently selected role. save_role saves the selected role with its current settings to Active Directory. delete_role deletes the selected role from Active Directory and from memory.

ADEdit Programmers Guide

262

Command descriptions

set_sd_owner
The set_sd_owner command sets the owner of a security descriptor (SD). It takes the SD in SDDL (security descriptor definition language) form and the security identifier (SID) of the owner to set and returns the SD in SDDL form with the new owner set.

Syntax
set_sd_owner sddl_string owner_sid

Abbreviation
sso

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument sddl_string owner_sid Type string string Description Required. A security descriptor in SDDL format. Required. The security identifier (SID) of the owner to set.

Return value
This command returns an SD in SDDL format if successful. The SD contains the new owner set by the command.

Examples
This example sets a new owner for an SD. The SD is the first long string after the command; the SID of the new owner is the much shorter string at the end of the command.
set_sd_owner

O:DAG:DAD:AI(A;;RCWDWOCCDCLCSWRPWPLOCR;;;DA)(OA;;CCDC;bf967aba0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967a9c-0de6-11d0-a28500aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a768-00aa006e0529;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;5f20201079a5-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;bf967aba-0de611d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-9020-

Chapter 4 ADEdit command reference

263

Command descriptions

00c04fc2d4cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-9020-00c04fc2d3cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;037088f80ae1-11d2-b422-00a0c968f939;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e00a0c983f608;bf967a86-0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a9c-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967aba0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;LC;; ;RU)(A;CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA) S-1-5-21-1076040321332654908-468068287-1109

returns:
O:S-1-5-21-1076040321-332654908-4680682871109G:DAD:AI(A;;RCWDWOCCDCLCSWRPWPLOCR;;;DA)(OA;;CCDC;bf967aba0de6-11d0-a285-00aa003049e2;;AO)(OA;;CCDC;bf967a9c-0de6-11d0-a28500aa003049e2;;AO)(OA;;CCDC;bf967aa8-0de6-11d0-a28500aa003049e2;;PO)(A;;RCLCRPLO;;;AU)(OA;;CCDC;4828cc14-1437-45bc-9b07ad6f015e5f28;;AO)(OA;CIIOID;RP;4c164200-20c0-11d0-a76800aa006e0529;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;4c16420020c0-11d0-a768-00aa006e0529;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-9020-00c04fc2d4cf;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;5f202010-79a5-11d0-902000c04fc2d4cf;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;bc0ac24079a9-11d0-9020-00c04fc2d4cf;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RP;bc0ac240-79a9-11d0-9020-00c04fc2d4cf;bf967aba0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;59ba2f42-79a2-11d0-902000c04fc2d3cf;4828cc14-1437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;59ba2f4279a2-11d0-9020-00c04fc2d3cf;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b422-00a0c968f939;4828cc141437-45bc-9b07-ad6f015e5f28;RU)(OA;CIIOID;RP;037088f8-0ae1-11d2-b42200a0c968f939;bf967aba-0de6-11d0-a285-00aa003049e2;RU)(OA;CIIOID;RP;b7c69e6d2cc7-11d2-854e-00a0c983f608;bf967a86-0de6-11d0-a28500aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e-00a0c983f608;bf967a9c0de6-11d0-a285-00aa003049e2;ED)(OA;CIIOID;RP;b7c69e6d-2cc7-11d2-854e00a0c983f608;bf967aba-0de6-11d0-a285-

ADEdit Programmers Guide

264

Command descriptions

00aa003049e2;ED)(OA;CIIOID;RCLCRPLO;;4828cc14-1437-45bc-9b07ad6f015e5f28;RU)(OA;CIIOID;RCLCRPLO;;bf967a9c-0de6-11d0-a28500aa003049e2;RU)(OA;CIIOID;RCLCRPLO;;bf967aba-0de6-11d0-a28500aa003049e2;RU)(OA;CIID;RPWPCR;91e647de-d96f-4b70-9557d63ff4f3ccd8;;PS)(A;CIID;SDRCWDWOCCDCLCSWRPWPDTLOCR;;;EA)(A;CIID;L C;;;RU)(A;CIID;SDRCWDWOCCLCSWRPWPLOCR;;;BA)

Related commands

explain_sd converts an SD in SDDL format to a human-readable form. remove_sd_ace removes an access control entry (ACE) from an SD. add_sd_ace adds an access control entry to an SD.

Chapter 4 ADEdit command reference

265

Command descriptions

set_user_password
The set_user_password command sets a new password for an Active Directory (AD) user or computer in AD.

Syntax
set_user_password principal_UPN password

Abbreviation
sup

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument principal_UPN password Type string string Description Required. The user principal name (UPN) of the user or computer whose password will be reset. Required. The text string to set as the new password. If the string contains characters that might be misinterpreted by ADEdits Tcl interpreter ($, for example), enclose the string in braces {} so that all characters inside are interpreted literally with no substitutions.

Return value
This command returns nothing if successful.

Examples
set_user_password [email protected] {B4uC$work}

sets [email protected] password to B4uC$work.

Related commands
None.

ADEdit Programmers Guide

266

Command descriptions

set_zone_computer_field
The set_zone_computer_field command sets the value for a field (attribute) value in the currently selected zone computer stored in memory.
set_zone_computer_field does not set a field value stored in Active Directory for this zone

computer; it sets only the field in memory. You must save the zone computer before any changed fields take effect in Active Directory. If you select another zone computer or quit ADEdit before saving the zone computer, any field changes youve made since the last save wont take effect.

Syntax
set_zone_computer_field field value

Abbreviation
szcf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Has one possible value: cpus: the number of CPUs in the computer. Takes an integer. enabled: whether the zone computer is enabled in its zone or not. Set to 1 if enabled, 0 if not.

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Return value
This command returns nothing if successful.

Examples
set_zone_computer_field cpus 2

sets the current zone computers number of CPUs to 2.

Related commands

list_zone_computers returns a list of all zone computers in the current zone along with object data for each computer.

Chapter 4 ADEdit command reference

267

Command descriptions

get_zone_computers returns a Tcl list of the AD names of all zone computers in the current zone. new_zone_computer creates a new zone computer and stores it in memory as the currently selected zone computer. select_zone_computer retrieves a zone computer from Active Directory and stores it in memory as the selected zone user. get_zone_computer_field reads a field value from the currently selected zone computer. save_zone_computer saves the selected zone computer with its current settings to Active Directory. delete_zone_computer deletes the selected zone computer from Active Directory and from memory.

ADEdit Programmers Guide

268

Command descriptions

set_zone_field
The set_zone_field command sets the value for a field (attribute) value in the currently selected zone stored in memory. does not set a field value stored in Active Directory for this zone; it sets only the field in memory. You must save the zone before any changed fields take effect in Active Directory. If you select another zone or quit ADEdit before saving the zone, any field changes youve made since the last save wont take effect.
set_zone_field

Syntax
set_zone_field field value

Abbreviation
szf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Possible values are: parent (only if the currently selected zone is a tree zone): This zones parent zone. Takes the distinguished name (DN) of a zone. computers (only if the currently selected zone is a computer role): the computer group assigned to the selected computer role. Takes user principal name (UPN) of the computer group to use. nisdomain: the name of the NIS domain set up for agentless clients. Takes a string. If not set, the default is the zone name. sfudomain (only if the currently selected zone is an SFU zone): the Windows domain to associate with the SFU zone. Takes a domain name. uidnext: The user ID to start from when auto-assigning UID numbers to new users created in this zone. Takes an integer. UID uto-assignment is deprecateduse sid_to_uid instead. uidreserved: User ID numbers to reserve and not use for UID auto-assignment if auto-assignment is turned on. Takes an integer (100, for example) or an integer range (1-100, for example). defaultgid: The default primary group to join for a new user created in this zone. Takes a group ID (GID) value. May use environment variables. defaultgecos: The default GECOS data to assign a new user created in this zone. Takes a string that defines the data. May use environment variables. defaulthome: The default home directory to assign a new user created in this zone. Takes a string that defines a path. May use environment variables.

Chapter 4 ADEdit command reference

269

Command descriptions

Argument

Type

Description defaultshell: The default shell to assign a new user created in this zone. Takes a string that defines the shell. May use environment variables. availableshells: The shells available to choose from when adding a new user to the zone using the console. Takes a string that is a set of shell commands, each separated from the next by a colon (:). For example, /bin/bash:/bin/ csh:/bin/ksh gidnext: The group ID to start from when auto-assigning GID numbers to new users created in this zone. Takes an integer. Auto-assignment is deprecated. gidreserved: Group ID numbers to reserve and not use for GID autoassignment if auto-assignment is turned on by gidnext. Takes an integer (100, for example) or an integer range (1-100, for example). nssvar (only if the currently selected zone is a tree zone) is an NSS substitution variable to add to the zones list of substitution variables. Takes a string of the form variablename=value . For example, A=B. To remove a variable, specify nothing on the right side of the equation. A=, for example, removes the A=B variable from the zones substitution variable list.

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Return value
This command returns nothing if successful.

Examples
set_zone_field computers [email protected]

sets the computer group associated with the currently selected computer role to linux_machines in the domain acme.com.
szf parent CN=global,CN=zones,CN=Centrify,CN=Program Data,DC=acme,DC=com

sets the parent zone of the current zone to global in the domain acme.com.

Related commands

create_zone creates a new zone in Active Directory. get_zones returns a Tcl list of all zones within a specified domain. select_zone retrieves a zone from Active Directory and stores it in memory as the currently selected zone. get_zone_field reads a field value from the currently selected zone. get_zone_nss_vars returns the NSS substitution variable for the selected zone. get_child_zones returns a Tcl list of child zones, computer roles, or computer zones associated with the current zone. save_zone saves the selected zone with its current settings to Active Directory.

ADEdit Programmers Guide

270

Command descriptions

delete_zone deletes the selected zone from Active Directory and memory. delegate_zone_right delegates a zone use right to a specified user or computer.

Chapter 4 ADEdit command reference

271

Command descriptions

set_zone_group_field
The set_zone_group_field command sets the value for a field (attribute) value in the currently selected zone group stored in memory.
set_zone_group_field

does not set a field value stored in Active Directory for this zone group; it sets only the field in memory. You must save the zone group before any changed fields take effect in Active Directory. If you select another zone group or quit ADEdit before saving the zone group, any field changes youve made since the last save wont take effect.

Syntax
set_zone_group_field field value

Abbreviation
szgf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Fields are standard etc/ group fields for a group account. Possible values are: name: the group name. A text string. gid: the group ID. A positive integer. required: the zone group is required for members in this zone. A user assigned to this group cannot remove the group from their active set of groups. Takes 1, y or Y for required; any other value is interpreted as not required

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Return value
This command returns nothing if successful.

Examples
set_zone_group_field name managers

sets the current zone groups UNIX group name to managers.

ADEdit Programmers Guide

272

Command descriptions

Related commands

list_zone_groups returns a list of all zone groups in the current zone along with the object data for each group. get_zone_groups returns a Tcl list of the AD names of all zone groups in the current zone. new_zone_group creates a new zone group and stores it in memory as the currently selected zone group. select_zone_group retrieves a zone group from Active Directory and stores it in memory as the selected zone group. get_zone_group_field reads a field value from the currently selected zone group. save_zone_group saves the selected zone group with its current settings to Active Directory. delete_zone_group deletes the selected zone group from Active Directory and from memory.

Chapter 4 ADEdit command reference

273

Command descriptions

set_zone_user_field
The set_zone_user_field command sets the value for a field (attribute) value in the currently selected zone user stored in memory.
set_zone_user_field

does not set a field value stored in Active Directory for this zone user; it sets only the field in memory. You must save the zone user before any changed fields take effect in Active Directory. If you select another zone user or quit ADEdit before saving the zone user, any field changes youve made since the last save wont take effect.

Syntax
set_zone_user_field field value

Abbreviation
szuf

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument field Type string Description Required. The name of the field whose value to set. Fields are standard etc/ passwd fields for a user account. Possible values are: uname: the username. A text string. Note that if there are multiple SFU zones in the forest, and you are setting this field in an SFU zone, this name must be unique among all the SFU zones. If you duplicate an existing username in another SFU zone, that user will be moved to the currently selected SFU zone when you save the zone user. uid: the user ID. A positive integer. gid: the group ID. A positive integer. gecos: user account information. A text string. home: users home directory. A text string. shell: users shell type. A text string enabled: whether user is enabled or not. 1, Y, or y is enabled, all other values specify disabled. Note that this field is only available for users in a classic zone. All other zone types use roles instead of enabled/disabled.

value

depends Required. The value to assign to the specified field. See the field descriptions for on field value types. Assign - to a field to unset the field to no value at all.

Return value
This command returns nothing if successful.

ADEdit Programmers Guide

274

Command descriptions

Examples
set_zone_user_field uname buzz

sets the current zone users UNIX username to buzz.

Related commands

list_zone_users returns a list of all zone users in the current zone along with the NSS data for each user. get_zone_users returns a Tcl list of the AD names of all zone users in the current zone. new_zone_user creates a new zone user and stores it in memory as the currently selected zone user. select_zone_user retrieves a zone user from Active Directory and stores it in memory as the selected zone user. get_zone_user_field reads a field value from the currently selected zone user. save_zone_user saves the selected zone user with its current settings to Active Directory. delete_zone_user deletes the selected zone user from Active Directory and from memory.

Chapter 4 ADEdit command reference

275

Command descriptions

show
The show command displays the current context of ADEdit: what domains its bound to, and what objects are currently selected. The command shows all available data for each selected object stored in memory. Note that any stored object data returned here is the state of the data as it exists in memory. If the object has been changed by ADEdit but not yet saved back to Active Directory, the object data returned will not match the object data as it is stored in Active Directory.

Syntax
show [all|bind|zone|user|computer|assignment|object|group|pamright| dzcommand|nismap|role|license]

Abbreviation
None.

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument [all|user|bind|zone| user|computer| assignment|object| group|pamright| dzcommand|nismap| role|license] Type string Description Takes one of following values. If no argument is supplied, the default is all. all returns the complete context of ADEditall of its current bindings and all currently selected objects in memory. bind returns ADEdits currently bound domains and the server bound in each domain. zone returns the currently selected zone. user returns the currently selected user object. computer returns the currently selected zone computer. assignment returns the currently selected role assignment object returns the currently selected AD object. group returns the currently selected zone group. pamright returns the currently selected PAM application. dzcommand returns the currently selected DirectAuthorize command. nismap returns the currently selected NIS map. role returns the currently selected role. license returns the forest list where valid licenses have been found (it only reports the forests that have been queried).

ADEdit Programmers Guide

276

Command descriptions

Return value
This command returns domain bindings and/or object data, depending on the supplied argument.

Examples
show

returns:
Bindings: acme.com: calla.acme.com Current zone: CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com Current nss user: [email protected]:adam:10001:10001:%{u:samaccountname}:%{home}/ %{user}:%{shell}:

Related commands
None.

Chapter 4 ADEdit command reference

277

Command descriptions

sid_to_escaped_string
The sid_to_escaped_string command takes a security identifier (SID) and converts it to escaped string format that works in an LDAP filter.

Syntax
sid_to_escaped_string sid

Abbreviation
stes

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument sid Type string Description Required. A security identifier (SID).

Return value
This command returns an escaped string form of the supplied SID.

Examples
sid_to_escaped_string S-1-5-21-2076040321-3326545908-468068287-1157

returns:
\01\05\00\00\00\00\00\05\15\00\00\00\81\dc\bd\7b\f4\0f\47\c6\bf\27\e6\1b\85\ 04\00\00

Related commands

sid_to_uid converts an AD SID to a user ID (UID). principal_from_sid searches Active Directory for an SID and returns the security principal associated with the SID.

ADEdit Programmers Guide

278

Command descriptions

sid_to_uid
The sid_to_uid command takes a security identifier (SID) of an AD user, looks up the AD user in Active Directory, and converts data there to a user ID (UID). This process is the same process used in the DirectControl consoles express mode to generate UIDs for users.

Syntax
sid_to_uid sid

Abbreviation
stu

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument sid Type string Description Required. A security identifier (SID).

Return value
This command returns a user ID.

Examples
sid_to_uid S-1-5-21-2076040321-3326545908-468068287-1157

returns: 1874853888

Related commands

principal_from_sid searches Active Directory for an SID and returns the security principal associated with the SID.

Chapter 4 ADEdit command reference

279

Command descriptions

validate_license
The validate_license command takes a path specification to the Centrify license container and determines if there is a valid license. If there is, the command stores an indicator in the ADEdit current context. If it does not find a valid license it reports an error and exits. be called multiple times. Successive indicators take precedence. It writes separate indicators for each forest (each license is per forest). Use the show license command to see the list of forests that have been found to have a valid license. Do not call validate_license before you bind to the domain. The validate_license context is deleted when ADEdit exits. ADEdit requires a valid license before a zone is created. The create_zone command does an implicit search. Thus, you can just call create_zone and let it find the container and validate the license. If it fails, use validate_license to validate the license container explicitly.
validate_license can

Syntax
validate_license path

Abbreviation
vl

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument path Type string Description Required. The path is the license containers distinguished name (DN).

Return value
This command returns nothing.

Examples
validate_license CN=Licenses,CN=UNIX,DC=acme,DC=com

This command looks in the acme.com\UNIX\Licenses folder for the Centrify license container.

ADEdit Programmers Guide

280

Command descriptions

Related commands

bind defines the current domain create_zone does in implicit validate license during execution show
license

command lists all forests that have a valid license.

Chapter 4 ADEdit command reference

281

Chapter 5

ade_lib Tcl library reference

This chapter describes the commands available in the ade_lib Tcl library, a set of utility Tcl procedures that use ADEdit commands to perform common administrative tasks. The command descriptions here are in alphabetical order to make each command easy to find. A preliminary section lists the commands in logical order with a short description of each command to help you find the command to match a particular task. Each command in the logical section links to the full command description later in the chapter.

Using the ade_lib Tcl library

The ade_lib Tcl library is a Tcl script, ade_lib.tcl, that is installed with ADEdit. To use ade_lib in a Tcl script or in an ADEdit session, begin the script or session with:
package require ade_lib

When executed, this command returns the version number of ade_lib and makes all of its procedures available as commands.

Command synopsis
ade_lib Tcl library commands fall into these logical groups. Click on a command name to go to the full description of the command.

Managing users and groups

These commands create AD users and groups and zone users and groups. They also add and remove users from groups. create_aduser creates a new AD user account and sets its password.

create_adgroup creates a new AD security group account and specifies its scope. create_user creates a new zone user based on an existing AD user, assigns field values to the new user, and saves the new user to AD. create_group creates a new zone group based on an existing AD group, assigns it a UNIX name and group ID, and saves the new group to AD. add_user_to_group adds an AD user to an AD group. remove_user_from_group removes an AD user from an AD group.

282

Command descriptions

Handling common DirectControl tasks

These commands perform a miscellaneous set of common DirectControl tasks. list_zones returns a list of zones in a specified domain to stdout along with zone type and zone schema for each zone.

create_assignment creates a new role assignment and saves it to AD. precreate_computer creates a zone computer profile and, if necessary, a new AD computer account for a UNIX computer without joining the computer to AD. It may also specify a set of one or more users or groups who can join the computer later to AD whether or not the users or groups have AD permission to do so.

Managing values
These commands manage common values in AD and DirectControl, converting them to informative formats and manipulating them for use in ADEdit commands. convert_msdate converts a Microsoft date value from an AD object field into humanreadable form.

explain_groupType converts a groupType value from an AD object into human-readable form. explain_trustAttributes converts a trustAttributes value from an AD object into humanreadable form. explain_trustDirection converts a trustDirection value from an AD object into humanreadable form. explain_userAccountControl converts a userAccountControl value from an AD object into human-readable form. modify_timebox modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field.

Command descriptions
The rest of the chapter describes each ade_lib Tcl library command in detail. Commands are in alphabetical order. The syntax of each command shows optional elements in [square brackets]. It shows variables in italics.

Chapter 5 ade_lib Tcl library reference

283

Command descriptions

add_user_to_group
The add_user_to_group command adds an Active Directory user to an AD group.

Syntax
add_user_to_group user group

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument user group Type string string Description Required. The user principal name (UPN) of the AD user to add. Required. The UPN of the AD group to which to add the user.

Return value
This command returns nothing if successful.

Examples
add_user_to_group [email protected] [email protected]

Related ade_lib Tcl library commands

create_aduser creates a new AD user account and sets its password. create_adgroup creates a new AD group account and specifies its scope. create_user creates a new zone user based on an existing AD user, assigns field values to the new user, and saves the new user to AD. create_group creates a new zone group based on an existing AD group, assigns it a UNIX name and group ID, and saves the new group to AD. remove_user_from_group removes an AD user from an AD group.

ADEdit Programmers Guide

284

Command descriptions

convert_msdate
The convert_msdate command accepts a Microsoft date value from an AD object field such as pwdLastSet and converts it into human-readable form.

Syntax
convert_msdate msdate

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument msdate Type string Description Required. A Microsoft date value for conversion.

Return value
This command returns the day of the week, the day of the month, the time of day using a 24-hour clock, the time zone, and the year.

Examples
convert_msdate [get_object_field pwdLastSet]

returns:
Thu Mar 24 14:40:26 PDT 2010

The unseen value returned by get_object_field pwdLastSet in this example was 12914026824062500, which was converted to a human-readable time and date.

Related ade_lib Tcl library commands

explain_groupType converts a groupType value from an AD object into human-readable form. explain_trustAttributes converts a trustAttributes value from an AD object into humanreadable form. explain_trustDirection converts a trustDirection value from an AD object into humanreadable form. explain_userAccountControl converts a userAccountControl value from an AD object into human-readable form.

Chapter 5 ade_lib Tcl library reference

285

Command descriptions

modify_timebox modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field.

ADEdit Programmers Guide

286

Command descriptions

create_adgroup
The create_adgroup command creates a new Active Directory group account with a specified distinguished name (DN), sAMAccountName, and group scope.

Syntax
create_adgroup dn sam gtype

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument dn sam gscope Type string string string Description Required. The distinguished name of the new group. Required. The sAMAccountName of the new group. Required. The scope for the new group. Takes these possible values: global universal local

Return value
This command returns nothing if successful.

Examples
create_adgroup {CN=pubs,CN=Users,DN=acme,DN=com} pubs global

Related ade_lib Tcl library commands

create_aduser creates a new AD user account and sets its password. create_user creates a new zone user based on an existing AD user, assigns field values to the new user, and saves the new user to AD. create_group creates a new zone group based on an existing AD group, assigns it a UNIX name and group ID, and saves the new group to AD. add_user_to_group adds an AD user to an AD group. remove_user_from_group removes an AD user from an AD group.

Chapter 5 ade_lib Tcl library reference

287

Command descriptions

create_aduser
The create_aduser command creates a new Active Directory user account with a specified distinguished name (DN), user principal name (UPN), sAMAccountName, and password.

Syntax
create_aduser dn upn sam pw

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument dn upn sam pw Type string string string string Description Required. The distinguished name of the new user. Required. The user principal name of the new user. Required. The sAMAccountName of the new user. Required. The password for the new user.

Return value
This command returns nothing if successful.

Examples
create_aduser {CN=ulysses urkham,CN=Users,DC=acme,DC=com} [email protected] ulysses.urkham {5$6fEr2B}

creates a new AD user account [email protected].

Related ade_lib Tcl library commands

create_adgroup creates a new AD group account and specifies its scope. create_user creates a new zone user based on an existing AD user, assigns field values to the new user, and saves the new user to AD. create_group creates a new zone group based on an existing AD group, assigns it a UNIX name and group ID, and saves the new group to AD. add_user_to_group adds an AD user to an AD group. remove_user_from_group removes an AD user from an AD group.

ADEdit Programmers Guide

288

Command descriptions

create_assignment
The create_assignment command creates a new role assignment and saves it to Active Directory

Syntax
create_assignment upn role[/zonename]

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument upn role[zonenem] Type string string Description Required. The user principal name of the AD user or group to assign the role to. Required. The name of the role to assign and (optional) the name of the zone in which the role is assigned. If the zone name is present, a slash(/) separates the role name and the zone name. If the zone name isnt present, the role assignment occurs in the currently selected zone.

Return value
This command returns nothing if successful.

Examples
create_assignment {CN=ulysses urkham,CN=Users,DC=acme,DC=com} servicereps/ support

creates a role assignment that assigns the role servicereps to user Ulysses Urkham in the zone support.

Related ade_lib Tcl library commands

None.

Chapter 5 ade_lib Tcl library reference

289

Command descriptions

create_group
The create_group command creates a new zone group for the currently selected zone and bases the new group on an existing Active Directory group. It assigns group data to the new group that includes the UNIX group name and the UNIX group ID.

Syntax
create_group adg name gid

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument adg name gid Type string string string Description Required. The user principal name of the AD group to use as the basis for the new zone group. Required. The UNIX group name of the new zone group. In a tree zone, - unsets the name value. Required. The UNIX group ID to assign to the new zone group. In a tree zone, - unsets the gid value.

Return value
This command returns nothing if successful.

Examples
create_group [email protected] pubs 1094

Related ade_lib Tcl library commands

create_aduser creates a new AD user account and sets its password. create_adgroup creates a new AD group account and specifies its scope. create_user creates a new zone user based on an existing AD user, assigns field values to the new user, and saves the new user to AD. add_user_to_group adds an AD user to an AD group. remove_user_from_group removes an AD user from an AD group.

ADEdit Programmers Guide

290

Command descriptions

create_user
The create_user command creates a new zone user for the currently selected zone and bases the new zone user on an existing Active Directory user. It assigns user data to the new user that includes user name, user ID, group ID, GECOS data, home directory, shell type, and role (or enabled/disabled for classic zones). You can assign the new user a role in a non-classic zone or you can enable or disable the new user in a classic zone. In a non-classic zone, create_user uses whatever role you specify to create a new role assignment object that links the new zone user to the specified role.

Syntax
create_user ad uname uid gid gecos home shell role

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument ad uname uid gid gecos Type string string string string string Description Required. The user principal name of the AD user to use as the basis for the new zone user. Required. The user name of the new zone user. Supply a dash (-) for this argument to set no user name (tree zone only). Required. The user ID for the new zone user. Supply a dash (-) for this argument to set no user ID (tree zone only). Required. The group ID for the new zone user. Supply a dash (-) for this argument to set no group ID (tree zone only). Required. The GECOS value (new user account information) for the new zone user. Supply a dash (-) for this argument to set no GECOS value (tree zone only). Note: you cant set the GECOS value if the currently selected zone is a classic zone. Required. The home directory for the new zone user. Supply a dash (-) for this argument to set no home directory (tree zone only). Required. The shell type for the new zone user. Supply a dash (-) for this argument to set no shell type (tree zone only).

home shell role

string string

string or Required. The role to assign to the new zone user (if the currently selected zone Boolean is a non-classic zone) or whether to enable or disable the new zone user (if the value currently selected zone is a classic zone.) 1, Y, or y enables the user; any other value disables the user (in a classic zone). Supply a dash (-) for this argument to set no role or not to specify enabled/disabled (tree zone only).

Chapter 5 ade_lib Tcl library reference

291

Command descriptions

Return value
This command returns nothing if successful.

Examples
create_user [email protected] ulysses 1005 - - %{home}/%{user} %{shell} -

This example creates a zone user ulysses based on the AD user [email protected]. It sets a UID, does not set a GID or GECOS value by using dashes, sets home and shell values, and does not set a role value (specified by using a dash).

Related ade_lib Tcl library commands

create_aduser creates a new AD user account and sets its password. create_adgroup creates a new AD group account and specifies its scope. create_group creates a new zone group based on an existing AD group, assigns it a UNIX name and group ID, and saves the new group to AD. add_user_to_group adds an AD user to an AD group. remove_user_from_group removes an AD user from an AD group.

ADEdit Programmers Guide

292

Command descriptions

explain_groupType
The explain_groupType command converts a groupType value from an AD object field into human-readable form.

Syntax
explain_groupType gt

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument gt Type string Description Required. A groupType value for conversion.

Return value
This command returns a hexadecimal version of the supplied value followed by the names of any flags that are set in the value.

Examples
explain_groupType [get_object_field groupType]

returns:
80000004 DOMAIN_LOCALSECURITY

The unseen value returned by get_object_field groupType in this example was 2147483644, which was converted to the hexadecimal value 80000004 and the name of the set flag DOMAIN_LOCALSECURITY.

Related ade_lib Tcl library commands

convert_msdate converts a Microsoft date value from an AD object field into humanreadable form. explain_trustAttributes converts a trustAttributes value from an AD object into humanreadable form. explain_trustDirection converts a trustDirection value from an AD object into humanreadable form. explain_userAccountControl converts a userAccountControl value from an AD object into human-readable form.

Chapter 5 ade_lib Tcl library reference

293

Command descriptions

modify_timebox modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field.

ADEdit Programmers Guide

294

Command descriptions

explain_trustAttributes
The explain_trustAttributes command converts a trustAttributes value from an AD object field into human-readable form.

Syntax
explain_trustAttributes ta

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument ta Type string Description Required. A trustAttributes value for conversion.

Return value
This command returns a hexadecimal version of the supplied value followed by the names of any flags that are set in the value.

Examples
explain_trustAttributes [get_object_field trustAttributes]

returns:
8 FOREST_TRANSITIVE

The unseen value returned by get_object_field trustAttributes in this example was 8, which was converted to the hexadecimal value 8 and the name of the set flag DOMAIN_LOCALSECURITY.

Related ade_lib Tcl library commands

convert_msdate converts a Microsoft date value from an AD object field into humanreadable form. explain_groupType converts a groupType value from an AD object into human-readable form. explain_trustDirection converts a trustDirection value from an AD object into humanreadable form. explain_userAccountControl converts a userAccountControl value from an AD object into human-readable form.

Chapter 5 ade_lib Tcl library reference

295

Command descriptions

modify_timebox modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field.

ADEdit Programmers Guide

296

Command descriptions

explain_trustDirection
The explain_trustDirection command converts a trustDirection value from an AD object field into human-readable form.

Syntax
explain_trustDirection td

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument td Type string Description Required. A trustDirection value for conversion.

Return value
This command returns the English version of the trust direction specified by the trustDirection value.

Examples
explain_trustDirection [get_object_field trustDirection]

returns:
two-way

Related ade_lib Tcl library commands

convert_msdate converts a Microsoft date value from an AD object field into humanreadable form. explain_groupType converts a groupType value from an AD object into human-readable form. explain_trustAttributes converts a trustAttributes value from an AD object into humanreadable form. explain_userAccountControl converts a userAccountControl value from an AD object into human-readable form. modify_timebox modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field.

Chapter 5 ade_lib Tcl library reference

297

Command descriptions

explain_userAccountControl
The explain_userAccountControl command converts a userAccountControl value from an AD object field into human-readable form.

Syntax
explain_userAccountControl uac

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument uac Type string Description Required. A userAccountControl value for conversion.

Return value
This command returns a hexadecimal version of the supplied value followed by the names of any flags that are set in the value.

Examples
explain_userAccountControl [get_object_field userAccountControl]

returns:
10200 ADS_UF_NORMAL_ACCOUNT ADS_UF_DONT_EXPIRE_PASSWD

The unseen value returned by get_object_field userAccountControl in this example was 66048, which was converted to the hexadecimal value 10200 and the name of the set flags ADS_UF_NORMAL_ACCOUNT and ADS_UF_DONT_EXPIRE_PASSWD.

Related ade_lib Tcl library commands

convert_msdate converts a Microsoft date value from an AD object field into humanreadable form. explain_groupType converts a groupType value from an AD object into human-readable form. explain_trustAttributes converts a trustAttributes value from an AD object into humanreadable form. explain_trustDirection converts a trustDirection value from an AD object into humanreadable form.

ADEdit Programmers Guide

298

Command descriptions

modify_timebox modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field.

Chapter 5 ade_lib Tcl library reference

299

Command descriptions

list_zones
The list_zones command lists the zones within a specified domain along with information about each zone. If executed in a script, this command outputs its list to stdout so that the output appears in the shell where the script is executed. The command does not return a Tcl list back to the executing script. Use the ADEdit command get_zones to return a Tcl list.

Syntax
list_zones domain

Options
This command takes no options.

Arguments
This command takes the following argument:
Argument domain Type string Description Required. The name of the domain in which to list zones.

Return value
This command returns a list to stdout of the zones within the specified domain. Each entry in the list contains: The zones distinguished name (DN)

The zone type The schema used in the zone

Each entry component is separated from the next by a colon (:).

Examples
list_zones

returns:
{CN=default,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} : classic4 : std {CN=cz1,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} : tree : std {CN=cz2,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} : tree : std {CN=global,CN=Zones,CN=Centrify,CN=Program Data,DC=acme,DC=com} : tree : rfc

Related ade_lib Tcl library commands

create_assignment creates a new role assignment and saves it to AD.

ADEdit Programmers Guide

300

Command descriptions

precreate_computer creates a zone profile and, if necessary, a new AD computer account for a UNIX computer without joining the computer to AD. It may also specify a set of one or more users or groups who can join the computer later to AD whether or not they have AD permission to do so.

Chapter 5 ade_lib Tcl library reference

301

Command descriptions

modify_timebox
The modify_timebox command modifies a timebox value that defines the hours of a week when a role is enabled or disabled. The command defines an hour of the week and then enables or disables that hour in the timebox value. This command is very useful in the set_role_field ADEdit command when setting the timebox field. Execute this command multiple times on a timebox value to set more than one hour in the value. For more information about the timebox value format, read the appendix Timebox value format on page 308.

Syntax
modify_timebox strTimeBox day hour avail

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument strTimeBox Type Description

hexaA 42-digit hexadecimal timebox value. A value of zero disables all hours of the decimal week. A value of FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF enables all integer hours of the week. integer integer Required. The day of the week when the hour occurs. 0=Sunday, 1=Monday, and so on to 6=Saturday. Required. The hour of the day to enable or disable. Takes a value from 0 to 23. 0 is from midnight to 1 AM, 1 is from 1 AM to 2 AM, and so on to 23, which is from 11 PM to midnight. Required. Whether to enable or disable the specified hour. 0=disable; all other values=enable.

day hour

avail

integer

Return value
This command returns a hexadecimal value that is the timebox value after enabling or disabling the specified hour of the week.

Examples
set tb 000000000000000000000000000000000000000000 set tb [modify_timebox $tb 6 23 1]

returns:
800000000000000000000000000000000000000000

ADEdit Programmers Guide

302

Command descriptions

Related ade_lib Tcl library commands

convert_msdate converts a Microsoft date value from an AD object field into humanreadable form. explain_groupType converts a groupType value from an AD object into human-readable form. explain_trustAttributes converts a trustAttributes value from an AD object into humanreadable form. explain_trustDirection converts a trustDirection value from an AD object into humanreadable form. explain_userAccountControl converts a userAccountControl value from an AD object into human-readable form.

Chapter 5 ade_lib Tcl library reference

303

Command descriptions

precreate_computer
The precreate_computer command creates a zone profile for a computer in Active Directory before that computer uses adjoin to join the network through AD. The zone profile is usually created by adjoin when a computer joins the network, which is why creating a zone profile before joining is called precreating a computer account. The zone profile is part of an AD computer object. If an AD computer object doesnt exist, precreate_computer can create one and then add a zone profile to the new AD computer object. The zone profile is in ADEdits currently selected zone. precreate_computer can also specify a container where AD will store the new AD computer object.
precreate_computer can create a service connection point (an AD serviceConnectionPoint

child object) for a new AD computer object. It can also create a computer zone (a machinelevel zone override, in essence a one-computer zone) for the precreated computer. sets the AD computer objects password and permissions when creating a zone profile. The password is the computers host name in lower case. The permissions the computer object has are: Read and Write permissions to the operatingSystemServicePack, operatingSystem, and operatingVersion attributes of the computer object.
precreate_computer

Read permission for the userAccountControl attribute of the computer object. Validate write to the servicePrincipalName and dNSHostName attributes. may also specify a DNS name for the precreated computer.

precreate_computer precreate_computer

can specify one or more trustees for the precreated computer. Each trustee can be either a user or a group, and has the rights needed to join this computer to the precreated computer account using adjoin.

is similar to adjoin -precreate, but provides more options and flexibility. You may also precreate computer accounts using the DirectControl console. Youll find much more information about precreating computer accounts in the Administrators Guide.
precreate_computer

Syntax
precreate_computer samaccount@domain [-ad] [-scp] [-czone] [-all] [-container rdn] [-dnsname dnsname] [-trustee upn [-trustee upn] ...]

ADEdit Programmers Guide

304

Command descriptions

Options
This command takes the following options:
Option -ad Description Creates an AD computer object. precreate_computer wont create an AD computer object if it already exists for the computer specified by the argument upn. Note that if no options specify AD computer object creation and no AD computer object already exists, precreate_computer will fail. Creates a service connection point for the AD computer object. Creates a computer zone for the computer object. Creates an AD computer object (if one doesnt exist already), a service connection point for the computer object, and a computer zone for the computer object: in essence all of the previous three options combined. Stores the new AD computer object (if created) in the AD container specified by rdn, which is the relative distinguished name (RDN) of the container. The root of the specified AD container is the distinguished name (DN) of the current domain. precreate_computer appends the RDN to the root DN to come up with the container DN. Sets the DNS name for the computer account to the provided DNS name. If this option isnt present, precreate_computer automatically sets the DNS name for the computer account. It derives the DNS name from the computers sAMAccount name and the domain name. Gives the user or group specifed by upn (the UPN of the user or group) permission to join a computer to the precreated computer account. precreate_computer may have multiple trustee options, each specifying a different user or group, to specify multiple users and groups as trustees.

-scp -czone --all

-container rdn

-dnsname dnsname

-trustee upn

Arguments
This command takes the following argument:
Argument samaccount@domain Type string Description Required. The name of the computer and the domain to join. The computer name is a sAMAccount name in the form of <computer>$. An example: [email protected]

Return value
This command returns nothing if successful.

Examples
precreate_computer [email protected] -trustee [email protected] -trustee [email protected]

precreates a zone profile for the computer [email protected] and specifies as trustees Adam Avery and Martin Moore. It precreates the zone profile in whatever zone is currently selected in ADEdit.

Chapter 5 ade_lib Tcl library reference

305

Command descriptions

Related ade_lib Tcl library commands

list_zones returns a list of zones in a specified domain to stdout along with zone type and zone schema for each zone. create_assignment creates a new role assignment and saves it to AD.

ADEdit Programmers Guide

306

Command descriptions

remove_user_from_group
The remove_user_from_group command removes an Active Directory user from an AD group.

Syntax
remove_user_from_group user group

Options
This command takes no options.

Arguments
This command takes the following arguments:
Argument user group Type string string Description Required. The user principal name (UPN) of the AD user to remove. Required. The UPN of the AD group from which to remove the user.

Return value
This command returns nothing if successful.

Examples
remove_user_from_group [email protected] [email protected]

Related ade_lib Tcl library commands

create_aduser creates a new AD user account and sets its password. create_adgroup creates a new AD group account and specifies its scope. create_user creates a new zone user based on an existing AD user, assigns field values to the new user, and saves the new user to AD. create_group creates a new zone group based on an existing AD group, assigns it a UNIX name and group ID, and saves the new group to AD. add_user_to_group adds an AD user to an AD group.

Chapter 5 ade_lib Tcl library reference

307

Appendix A

Timebox value format

A role in DirectControl specifies a collection of rights. A role object contains a field, timebox, that defines what hours in a week a role is either enabled or disabled. Setting the timebox field in a role object defines when a roles rights are in effect. You can read a roles timebox field using the ADEdit command get_role_field and set the timebox value using set_role_field. You can modify an existing timebox value one hour at a time using the ADEdib library command modify_timebox. To interpret a timebox value, or to set it directly, you must know the timebox value format which is, unfortunately, not simple as defined by Active Directory. This appendix explains the format.

Hex string
The timebox value is a 42-character (21-byte) hexadecimal value stored as a string. When the hex value is converted to a binary value, its 168 bits each map to a single hour within the week. If a bit is set to 1, its corresponding hour is enabled for the role. If set to 0, its corresponding hour is disabled.

Hour mapping
Each day of the week takes three bytes (24 bits) to specify how its hours are enabled or disabled. The following tables show how the hours of a day are mapped to the bits within each of a days three bytes.

308

Hour mapping

Byte 0
Hour 12-1 AM 1-2 AM 2-3 AM 3-4 AM 4-5 AM 5-6 AM 6-7 AM 7-8 AM Bit 0 (least-significant bit) 1 2 3 4 5 6 7 (most-significant bit)

Byte 1
Hour 8-9 AM 9-10 AM 10-11 AM 11-12 AM 12-1 PM 1-2 PM 2-3 PM 3-4 PM Bit 0 (least-significant bit) 1 2 3 4 5 6 7 (most-significant bit)

Byte 2
Hour 4-5 PM 5-6 PM 6-7 PM 7-8 PM 8-9 PM 9-10 PM 10-11 PM 11-12 PM Bit 0 (least-significant bit) 1 2 3 4 5 6 7 (most-significant bit)

Appendix A Timebox value format

309

Day mapping

Day mapping
Each of the seven days in a week have three bytes within the 21-byte timebox value. These bytes are in chronological order from most-significant byte to least-significant byte. (Note that this is the opposite of chronological bit order within each byte, which is LSB to MSB.) The starting point of a week is 4 PM on Saturday afternoon. The table below shows how each days three bytes (0-2) map to the timebox values bytes, listed here in order from most-significant byte to least-significant byte.
Day byte Saturday, byte 2 Sunday, byte 0 Sunday, byte 1 Sunday, byte 2 Monday, byte 0 Monday, byte 1 Monday, byte 2 Tuesday, byte 0 Tuesday, byte 1 Tuesday, byte 2 Wednesday, byte 0 Wednesday, byte 1 Wednesday, byte 2 Thursday, byte 0 Thursday, byte 1 Thursday, byte 2 Friday, byte 0 Friday, byte 1 Friday, byte 2 Saturday, byte 0 Saturday, byte 1 Timebox value byte 20 (most-significant byte) 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 (least-significant byte)

ADEdit Programmers Guide

310

Appendix B

ADEdit command abbreviations

ADEdit offers abbreviations for most of its commands. Theyre listed with each command description and appear when you get help text for a command within ADEdit. Although abbreviations are most useful in interactive mode when entering commands repeatedly by hand, people sometimes use abbreviations in scripts, which can make the scripts hard to read. This appendix offers a table of command abbreviations listed in alphabetical order with their associated full-length names. You can use the table as ase-lookup table for abbreviated commands. It makes interpreting abbreviations in scripts a bit easier.
Command Abbreviation acr adinfo ame aov apr ase ccr cz dfdn dldzc dlme dlnm dlo dlpam dlr dlra dlz dlzc dlzg dlzu dnfd dntp Command add_command_to_role get_adinfo add_map_entry add_object_value add_pamapp_to_role add_sd_ace create_computer_role create_zone domain_from_dn delete_dz_command delete_map_entry delete_nis_map delete_object delete_pam_app delete_role delete_role_assignment delete_zone delete_zone_computer delete_zone_group delete_zone_user dn_from_domain dn_to_principal

311

Command Abbreviation gbi gcz gdzc gdzcf gep getr getzc ggm gnm gnmf gnms go gof gpam gpf gpn gpd gra graf grap grc grdn grf gsg gz gzcf gzf gzg gzgf gznv gzu gzuf h jgum

Command get_bind_info get_child_zones get_dz_commands get_dzc_field getent_passwd get_roles get_zone_computers get_group_members get_nis_map get_nis_map_field get_nis_maps get_objects get_object_field get_pam_apps get_pam_field get_pwname get_parent_dn get_role_assignments get_role_assignment_field get_role_apps get_role_commands get_rdn get_role_field get_schema_guid get_zones get_zone_computer_field get_zone_field get_zone_groups get_zone_group_field get_zone_nss_vars get_zone_users get_zone_user_field help joined_get_user_membership

ADEdit Programmers Guide

312

Command Abbreviation jntp jug lsdzc lsnm lsnms lspa lsr lsra lsrr lszc lszg lszu newdzc newnm newo newpam newr newra newzc newzg newzu pfs ptd q rcfr rov rpamfr rsa sdzcf sldzc slnm slo slpam slr

Command joined_name_to_principal joined_user_in_group list_dz_commands list_nis_map list_nis_maps list_pam_apps list_roles list_role_assignments list_role_rights list_zone_computers list_zone_groups list_zone_users new_dz_command new_nis_map new_object new_pam_app new_role new_role_assignment new_zone_computer new_zone_group new_zone_user principal_from_sid principal_to_dn quit remove_command_from_role remove_object_value remove_pamapp_from_role remove_sd_ace set_dzc_field select_dz_command select_nis_map select_object select_pam_app select_role

Appendix B ADEdit command abbreviations

313

Command Abbreviation slra slz slzc slzg slzu sof spf sraf srf sso stes stu sup svdzc svnm svo svpam svr svra svz svzc svzg svzu szcf szf szgf szuf

Command select_role_assignment select_zone select_zone_computer select_zone_group select_zone_user set_object_field set_pam_field set_role_assignment_field set_role_field set_sd_owner sid_to_escaped_string sid_to_uid set_user_password save_dz_command save_nis_map save_object save_pam_app save_role save_role_assignment save_zone save_zone_computer save_zone_group save_zone_user set_zone_computer_field set_zone_field set_zone_group_field set_zone_user_field

Commands that dont have abbreviations: bind, delegate_zone_right, delete_sub_tree, explain_sd, pop, push, set_ldap_timeout, and show.

ADEdit Programmers Guide

314

Index
A
abbreviations 25 Active Directory 17 data propagation 28 AD object 20 creating new 30 examining properties 31 field values 31 fields 30 in context 30 modification 32 reading 27 saving 20, 21, 27, 33 selected 20 selection 27, 29 selection persistence 30 types 21, 29 adclient 17, 24, 29 add_command_to_role command 43 add_map_entry command 45 add_object_value command 47 add_pamapp_to_role command 49 add_sd_ace command 51 add_user_to_group command 284 ade_lib 19, 24 ade_lib commands common DirectControl tasks 283 managing users and groups 282 managing values 283 ade_lib Tcl library 15, 19, 282 using in Tcl script 282 ADEdit administration scope 14 as Tcl application 9 cautions 9 components 18 examples of use 15 execution 24 execution modes 14 features 14 installation 24 interactive mode 15, 19 operating environment 17 purpose 9, 14 scripting 15 stateful nature 27 syntax 24 Tcl script execution 15 typical logic flow 26 ADEdit application 19 ADEdit command set 21 ADEdit script 19, 26 as executable file 15 execution as a UNIX-executable file 26 execution using ADEdit 26 adflush 18 administration tools conflicts 18, 21 adquery 14 adupdate 14 arguments 24

B
bind command 27, 54 binding 20, 27 authentication 20, 28 difference from joining 29 scope 28

C
Centrify contacting 12 CLI commands Centrify 18 command history 15, 25 commands abbreviations 311 AD object 41 ADEdit context 34 arguments 24 computer role 36 context 21

315

DirectAuthorize (DZ) 40 general-purpose 21, 34 going through adclient 29 new object 30 NIS map 41 object-management 21 object-management types 22 options 24 PAM application 40 results 25 role 39 role assignment 39 security descriptor 23, 36 selection 29 types 21 utility 35 zone 36 zone computer 38 zone group 37 zone user 37 context 20 cautions 21 examining 31 persistence 20 pushing 33 pushing and popping 21 selection as part of 30 conventions, documentation 10 convert_msdate command 285 create_adgroup command 287 create_aduser command 288 create_assignment command 289 create_computer_role command 31, 57 create_group command 290 create_user command 291 create_zone command 31, 59 credentials 28

delete_sub_tree command 75 delete_zone command 77 delete_zone_computer command 79 delete_zone_group command 81 delete_zone_user command 32, 82 DirectAuthorize 40 DirectControl API 18 DirectControl console 14, 18 dn_from_domain command 83 dn_to_principal command 84 documentation additional 11 conventions 10 domain binding 27 domain binding 14 domain controller 17, 18, 20, 27 selection 27 domain_from_dn command 85

E
errors 25 explain_groupType command 293 explain_sd command 86 explain_trustAttributes command 295 explain_trustDirection command 297 explain_userAccountControl command 298

G
get_adinfo command 89 get_bind_info command 32, 90 get_child_zones command 92 get_dz_commands command 94 get_dzc_field command 96 get_group_members command 100 get_nis_map command 101 get_nis_map_field command 103 get_nis_maps command 105 get_object_field command 107 get_objects command 109 get_pam_apps command 111 get_pam_field command 113 get_parent command 115 get_pwnam command 116 get_rdn command 117 get_role_apps command 118 get_role_assignment_field command 120

D
delegate_zone_right command 62 delete_dz_command command 64 delete_map_entry command 65 delete_nis_map command 67 delete_object command 69 delete_pam_app command 71 delete_role command 72 delete_role_assignment command 74

Book Title

316

get_role_assignments command 122 get_role_commands command 124 get_role_field command 126, 308 get_roles command 129 get_schema_guid command 131 get_zone_computer_field command 132 get_zone_computers command 134 get_zone_field command 136 get_zone_group_field command 139 get_zone_groups command 141 get_zone_nss_vars command 143 get_zone_user_field command 31, 145 get_zone_users command 147 get_zones command 30, 149 getent_passwd command 151

multi-master data store 17

N
new_dz_command command 177 new_nis_map command 179 new_object command 181 new_pam_app command 183 new_role command 185 new_role_assignment command 187 new_zone_computer command 189 new_zone_group command 191 new_zone_user command 31, 193

O
object - see AD object options 24

H
help command 26, 152

P
PAM 17 password enclosing in braces for Tcl handling 28 pop command 21, 33, 195 precreate_computer command 304 principal_from_sid command 196 principal_to_dn command 197 push command 21, 33, 199

J
joined_get_user_membership command 154 joined_name_to_principal command 155 joined_user_in_group command 156

K
Kerberos credentials cache 28

L
LDAP queries execution time interval 29 ldapsearch 14 list_dz_commands command 157 list_nis_map command 159 list_nis_maps command 161 list_pam_apps command 163 list_role_assignments command 165 list_role_rights command 167 list_roles command 169 list_zone_computers command 171 list_zone_groups command 173 list_zone_users command 175 list_zones command 300

Q
quit command 200

R
remove_command_from_role command 201 remove_object_value command 203 remove_pamapp_from_role command 205 remove_sd_ace command 207 remove_user_from_group command 307

S
save_dz_command command 210 save_nis_map command 212 save_object command 214 save_pam_app command 216 save_role command 218 save_role_assignment command 220 save_zone command 33, 222 save_zone_computer command 224

M
man pages source of information 12 modify_timebox command 302, 308

Index

317

save_zone_group command 226 save_zone_user command 228 select_dz_command command 230 select_nis_map command 232 select_object command 234 select_pam_app command 236 select_role command 238 select_role_assignment command 240 select_zone 30 select_zone command 242 select_zone_computer command 244 select_zone_group command 246 select_zone_user command 248 selecting an object 27 set_dzc_field command 250 set_ldap_timeout command 29, 254 set_object_field command 255 set_pam_field command 257 set_role_assignment_field command 259 set_role_field command 261, 308 set_sd_owner command 263 set_user_password command 266 set_zone_computer_field command 267 set_zone_field command 269 set_zone_group_field command 272 set_zone_user_field command 32, 274 show command 32, 276 sid_to_escaped_string command 278 sid_to_uid command 279 stack, context 33 stdout 25

Z
zone creation 31

T
Tcl core commands 19 interpreter 19 reference book 9, 19 syntax 28 Tcl list 25 technical support 13 timebox field value 308

V
validate_license 280

W
wildcard characters 26

Book Title

318