Centrify Suite

ADEdit Programmers GuideNovember 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.

Modifying or deleting selected objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Saving selected objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Pushing and popping context. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Contents

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100ADEdit Programmers Guide 4

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Contents 5

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226ADEdit Programmers Guide 6

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Contents 7

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 311

Index 315ADEdit Programmers Guide 8

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.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 audienceThis 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 guide9

Guide conventionsThis 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 conventionsWe 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 helpADEdit provides help text for each of its commands: simply enter help 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 informationYou 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 informationThe 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 DirectControl-specific 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 CorporationIf 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 Corporationwww.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 info@centrify.com.About this guide 13

Chapter 1replaces adupdate and adquery and offers the features of LDAP clients such as ldapsearch.

Execution

ADEdit offers multiple methods of execution: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 featuresADEdit 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 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 actionPart 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 actionincorrectly (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

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.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 environmentThis 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 DirectControl-specific 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 17

ADEdit componentsADEdit 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 componentsADEdit 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 componentsFigure 1. A user can access ADEdit through a CLI (a shell) or through an executing Tcl script or application. ADEdits Tcl interpreter executescommands it receives from the CLI using the ADEdit commands and Tcl commands that are part of ADEdit. It may also use ade_lib Tcl librarycommands if specified. Tcl scripts and applications use ADEdits commands and ade_lib Tcl library commands directly. ADEdit binds to an ActiveDirectory domain controller, with which it exchanges data. ADEdit may also (in a few cases) get data from Active Directory through the adclientprocess.

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.

UNIX/Linux/M ac com puter

ADEdit

Tcl Interpeter

Tcl Com m ands

ADEdit Com m ands

ade_lib Tcl library

Tcl Scrip ts CLI

User

Active D irectoryDomain Controller

adclientChapter 2 ADEdit overview 19

ADEdit contextADEdit contextWhen 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 setPushing 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 setADEdit 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_ 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_ 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_ 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_ 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_ 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__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__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 setnot change the attribute value in AD and wont have any effect until the object is saved to AD.

A save_ 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_ command, the new object disappears as soon as another object of that type is selected or when ADEdit quits.

A delete_ 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

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^&4Getting 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 useStandard 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 operationADEdit 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.24

Syntax and general operationIn 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 full-length 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 50-command capacity. Once full, the history drops old commands as new commands enter.Chapter 3 Getting started with ADEdit 25

Using ADEdit scriptsThe 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 scriptsYou 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.

2 Use chmod to make the file executable in UNIX (chmod +x yourfile, 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 flowUsing 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.

BindingADEdit 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 dcserv1@acme.comChapter 3 Getting started with ADEdit 27

BindingKeep 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 objectBinding 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 objectADEdit 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 objectobject 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 objectADEdit 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 contextfields 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 adam.avery@acme.com

In this example, new_zone_user finds the AD user adam.avery@acme.com 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 contextADEdits 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 adam.avery@acme.com.Chapter 3 Getting started with ADEdit 31

Modifying or deleting selected objectsGetting 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:

adam.avery@acme.com: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 objectsOnce 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 adam.avery@acme.com.)

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, adam.avery@acme.com from ADEdits context so theres no longer a selected zone user and also deletes the zone user object adam.avery@acme.com so theres no longer a zone user by that name in AD.ADEdit Prograrmmers Guide 32

Saving selected objectsNote 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 objectsAny 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 contextThere 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 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.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 groupsADEdit 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.34

Command groupsUtility 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 pri