release-notes-1-4-5-20071025
[openafs.git] / doc / html / UserGuide / auusg008.htm
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
2 <HTML><HEAD>
3 <TITLE>User Guide</TITLE>
4 <!-- Begin Header Records  ========================================== -->
5 <!-- /tmp/idwt3629/auusg000.scr converted by idb2h R4.2 (359) ID      -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 14:38:44                -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 14:38:42">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 14:38:42">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 14:38:42">
10 </HEAD><BODY>
11 <!-- (C) IBM Corporation 2000. All Rights Reserved    --> 
12 <BODY bgcolor="ffffff"> 
13 <!-- End Header Records  ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>User Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg007.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auusg009.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
17 <HR><H1><A NAME="HDRWQ60" HREF="auusg002.htm#ToC_112">Using Groups</A></H1>
18 <P>This chapter explains how to create groups and discusses
19 different ways to use them.
20 <HR><H2><A NAME="HDRWQ61" HREF="auusg002.htm#ToC_113">About Groups</A></H2>
21 <P>An AFS <I>group</I> is a list of specific users that you
22 can place on access control lists (ACLs). Groups make it much easier to
23 maintain ACLs. Instead of creating an ACL entry for every user
24 individually, you create one entry for a group to which the users
25 belong. Similarly, you can grant a user access to many directories at
26 once by adding the user to a group that appears on the relevant ACLs.
27 <P>AFS client machines can also belong to a group. Anyone logged into
28 the machine inherits the permissions granted to the group on an ACL, even if
29 they are not authenticated with AFS. In general, groups of machines are
30 useful only to system administrators, for specialized purposes like complying
31 with licensing agreements your cell has with software vendors. Talk
32 with your system administrator before putting a client machine in a group or
33 using a machine group on an ACL. 
34 <A NAME="IDX1025"></A>
35 <A NAME="IDX1026"></A>
36 <P>To learn about AFS file protection and how to add groups to ACLs, see <A HREF="auusg007.htm#HDRWQ44">Protecting Your Directories and Files</A>.
37 <P><H3><A NAME="HDRWQ62" HREF="auusg002.htm#ToC_114">Suggestions for Using Groups Effectively</A></H3>
38 <P>There are three typical ways to use groups, each suited to a
39 particular purpose: private use, shared use, and group use. The
40 following are only suggestions. You are free to use groups in any way
41 you choose.
42 <UL>
43 <P><LI><I>Private use</I>: you create a group and place it on the ACL
44 of directories you own, without necessarily informing the group's members
45 that they belong to it. Members notice only that they can or cannot
46 access the directory in a certain way. You retain sole administrative
47 control over the group, since you are the owner.
48 <A NAME="IDX1027"></A>
49 <A NAME="IDX1028"></A>
50 <P>The existence of the group and the identity of its members is not
51 necessarily secret. Other users can see the group's name on an ACL
52 when they use the <B>fs listacl</B> command, and can use the <B>pts
53 membership</B> command to display + the groups to which they themselves
54 belong. You can, however, limit who can display the members of the
55 group, as described in <A HREF="#HDRWQ74">Protecting Group-Related Information</A>.
56 <P><LI><I>Shared use</I>: you inform the group's members that they
57 belong to the group, but you are the group's sole owner and
58 administrator. For example, the manager of a work group can create a
59 group of all the members in the work group, and encourage them to use it on
60 the ACLs of directories that house information they want to share with other
61 members of the group. 
62 <A NAME="IDX1029"></A>
63 <A NAME="IDX1030"></A>
64 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If you place a group owned by someone else on your ACLs, the group's
65 owner can change the group's membership without informing you.
66 Someone new can gain or lose access in a way you did not intend and without
67 your knowledge.
68 </TD></TR></TABLE>
69 <P><LI><I>Group use</I>: you create a group and then use the <B>pts
70 chown</B> command to assign ownership to a group--either another group
71 or the group itself (the latter type is a <I>self-owned</I> group).
72 You inform the members of the owning group that they all can administer the
73 owned group. For instructions for the <B>pts chown</B> command, see
74 <A HREF="#HDRWQ73">To Change a Group's Owner</A>.
75 <A NAME="IDX1031"></A>
76 <A NAME="IDX1032"></A>
77 <A NAME="IDX1033"></A>
78 <A NAME="IDX1034"></A>
79 <A NAME="IDX1035"></A>
80 <P>The main advantage of designating a group as an owner is that several
81 people share responsibility for administering the group. A single
82 person does not have to perform all administrative tasks, and if the
83 group's original owner leaves the cell, there are still other people who
84 can administer it.
85 <P>However, everyone in the owner group can make changes that affect others
86 negatively: adding or removing people from the group inappropriately or
87 changing the group's ownership to themselves exclusively. These
88 problems can be particularly sensitive in a self-owned group. Using an
89 owner group works best if all the members know and trust each other; it
90 is probably wise to keep the number of people in an owner group small.
91 </UL>
92 <P><H3><A NAME="HDRWQ63" HREF="auusg002.htm#ToC_115">Group Names</A></H3>
93 <A NAME="IDX1036"></A>
94 <P>The groups you create must have names with two parts, in the following
95 format:
96 <P><VAR>   owner_name</VAR><B>:</B><VAR>group_name</VAR>
97 <P>The <VAR>owner_name</VAR> prefix indicates which user or group owns the group
98 (naming rules appear in <A HREF="#HDRWQ69">To Create a Group</A>). The <VAR>group_name</VAR> part indicates the
99 group's purpose or its members' common interest. Group names
100 must always be typed in full, so a short <VAR>group_name</VAR> is most
101 practical. However, names like <B>terry:1</B> and
102 <B>terry:2</B> that do not indicate the group's purpose are
103 less useful than names like <B>terry:project</B>.
104 <P>Groups that do not have the <VAR>owner_name</VAR> prefix possibly appear on
105 some ACLs; they are created by system administrators only. All of
106 the groups you create must have an <VAR>owner_name</VAR> prefix.
107 <P><H3><A NAME="Header_116" HREF="auusg002.htm#ToC_116">Group-creation Quota</A></H3>
108 <A NAME="IDX1037"></A>
109 <A NAME="IDX1038"></A>
110 <P>By default, you can create 20 groups, but your system administrators can
111 change your <I>group-creation quota</I> if appropriate. When you
112 create a group, your group quota decrements by one. When a group that
113 you created is deleted, your quota increments by one, even if you are no
114 longer the owner. You cannot increase your quota by transferring
115 ownership of a group to someone else, because you are always recorded as the
116 creator.
117 <P>If you exhaust your group-creation quota and need to create more groups,
118 ask your system administrator. For instructions for displaying your
119 group-creation quota, see <A HREF="#HDRWQ67">To Display A Group Entry</A>.
120 <HR><H2><A NAME="HDRWQ64" HREF="auusg002.htm#ToC_117">Displaying Group Information</A></H2>
121 <A NAME="IDX1039"></A>
122 <A NAME="IDX1040"></A>
123 <A NAME="IDX1041"></A>
124 <P>You can use the following commands to display information about groups and
125 the users who belong to them:
126 <UL>
127 <P><LI>To display the members of a group, or the groups to which a user belongs,
128 use the <B>pts membership</B> command.
129 <P><LI>To display the groups that a user or group owns, use the <B>pts
130 listowned</B> command.
131 <P><LI>To display general information about a user or group, including its name,
132 AFS ID, creator, and owner, use the <B>pts examine</B> command.
133 </UL>
134 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The <B>system:anyuser</B> and <B>system:authuser</B>
135 system groups do not appear in a user's list of group memberships, and
136 the <B>pts membership</B> command does not display their members.
137 For more information on the system groups, see <A HREF="auusg007.htm#HDRWQ50">Using the System Groups on ACLs</A>.
138 </TD></TR></TABLE>
139 <P><H3><A NAME="HDRWQ65" HREF="auusg002.htm#ToC_118">To Display Group Membership</A></H3>
140 <A NAME="IDX1042"></A>
141 <A NAME="IDX1043"></A>
142 <P>Issue the <B>pts membership</B> command to display the members of a
143 group, or the groups to which a user belongs.
144 <PRE>   % <B>pts membership</B> &lt;<VAR>user&nbsp;or&nbsp;group&nbsp;name&nbsp;or&nbsp;id</VAR>><SUP>+</SUP>
145 </PRE>
146 <P>where <VAR>user or group name or id</VAR> specifies the name or AFS UID of
147 each user for which to display group membership, or the name or AFS GID of
148 each group for which to display the members. If identifying a group by
149 its AFS GID, precede the GID with a hyphen (<B>-</B>) to indicate that it
150 is a negative number.
151 <P><H3><A NAME="Header_119" HREF="auusg002.htm#ToC_119">Example:  Displaying the Members of a Group</A></H3>
152 <A NAME="IDX1044"></A>
153 <P>The following example displays the members of the group
154 <B>terry:team</B>.
155 <PRE>   % <B>pts membership terry:team</B>
156    Members of terry:team (id: -286) are:
157      terry
158      smith 
159      pat
160      johnson
161 </PRE>
162 <P><H3><A NAME="Header_120" HREF="auusg002.htm#ToC_120">Example:  Displaying the Groups to Which a User Belongs</A></H3>
163 <P>The following example displays the groups to which users
164 <B>terry</B> and <B>pat</B> belong.
165 <PRE>   % <B>pts membership terry pat</B>
166    Groups terry (id: 1022) is a member of:
167      smith:friends
168      pat:accounting
169      terry:team
170    Groups pat (id: 1845) is a member of:
171      pat:accounting
172      sam:managers
173      terry:team
174 </PRE>
175 <P><H3><A NAME="HDRWQ66" HREF="auusg002.htm#ToC_121">To Display the Groups a User or Group Owns</A></H3>
176 <A NAME="IDX1045"></A>
177 <A NAME="IDX1046"></A>
178 <A NAME="IDX1047"></A>
179 <A NAME="IDX1048"></A>
180 <A NAME="IDX1049"></A>
181 <P>Issue the <B>pts listowned</B> command to display the groups that a
182 user or group owns.
183 <PRE>   %  <B>pts listowned</B> &lt;<VAR>user&nbsp;or&nbsp;group&nbsp;name&nbsp;or&nbsp;id</VAR>><SUP>+</SUP>
184 </PRE>
185 <P>where <VAR>user or group name or id</VAR> specifies the name or AFS UID of
186 each user, or the name or AFS GID of each group, for which to display group
187 ownership. If identifying a group by its AFS GID, precede the GID with
188 a hyphen (<B>-</B>) to indicate that it is a negative number.
189 <P><H3><A NAME="Header_122" HREF="auusg002.htm#ToC_122">Example:  Displaying the Groups a Group Owns</A></H3>
190 <A NAME="IDX1050"></A>
191 <P>The following example displays the groups that the group
192 <B>terry:team</B> owns.
193 <PRE>   % <B>pts listowned -286</B>
194    Groups owned by terry:team (id: -286) are:
195      terry:project
196      terry:planners
197 </PRE>
198 <P><H3><A NAME="Header_123" HREF="auusg002.htm#ToC_123">Example:  Displaying the Groups a User Owns</A></H3>
199 <A NAME="IDX1051"></A>
200 <P>The following example displays the groups that user <B>pat</B>
201 owns.
202 <PRE>   % <B>pts listowned pat</B>
203    Groups owned by pat (id: 1845) are:
204       pat:accounting
205       pat:plans
206    
207 </PRE>
208 <P><H3><A NAME="HDRWQ67" HREF="auusg002.htm#ToC_124">To Display A Group Entry</A></H3>
209 <A NAME="IDX1052"></A>
210 <A NAME="IDX1053"></A>
211 <A NAME="IDX1054"></A>
212 <A NAME="IDX1055"></A>
213 <A NAME="IDX1056"></A>
214 <A NAME="IDX1057"></A>
215 <A NAME="IDX1058"></A>
216 <A NAME="IDX1059"></A>
217 <A NAME="IDX1060"></A>
218 <P>Issue the <B>pts examine</B> command to display general information
219 about a user or group, including its name, AFS ID, creator, and owner.
220 <PRE>   %  <B>pts examine</B> &lt;<VAR>user&nbsp;or&nbsp;group&nbsp;name&nbsp;or&nbsp;id</VAR>><SUP>+</SUP>
221 </PRE>
222 <P>where <VAR>user or group name or id</VAR> specifies the name or AFS UID of
223 each user, or the name or AFS GID of each group, for which to display
224 group-related information. If identifying a group by its AFS GID,
225 precede the GID with a hyphen (<B>-</B>) to indicate that it is a negative
226 number.
227 <P>The output includes information in the following fields:
228 <DL>
229 <P><DT><B><TT>Name</TT>
230 </B><DD>For users, this is the character string typed when logging in. For
231 machines, the name is the IP address; a zero in address field acts as a
232 wildcard, matching any value. For most groups, this is a name of the
233 form <VAR>owner_name</VAR><B>:</B><VAR>group_name</VAR>. Some
234 groups created by your system administrator do not have the
235 <VAR>owner_name</VAR> prefix. See <A HREF="#HDRWQ63">Group Names</A>.
236 <P><DT><B><TT>id</TT>
237 </B><DD>This is a unique identification number that the AFS server processes use
238 internally. It is similar in function to a UNIX UID, but operates in
239 AFS rather than the UNIX file system. Users and machines have positive
240 integer AFS user IDs (UIDs), and groups have negative integer AFS group IDs
241 (GIDs).
242 <A NAME="IDX1061"></A>
243 <A NAME="IDX1062"></A>
244 <A NAME="IDX1063"></A>
245 <P><DT><B><TT>owner</TT>
246 </B><DD>This is the user or group that owns the entry and so can administer
247 it.
248 <P><DT><B><TT>creator</TT>
249 </B><DD>The name of the user who issued the <B>pts createuser</B> and <B>pts
250 creategroup</B> command to create the entry. This field is useful
251 mainly as an audit trail and cannot be changed.
252 <P><DT><B><TT>membership</TT>
253 </B><DD>For users and machines, this indicates how many groups the user or machine
254 belongs to. For groups, it indicates how many members belong to the
255 group. This number cannot be set explicitly.
256 <P><DT><B><TT>flags</TT>
257 </B><DD>This field indicates who is allowed to list certain information about the
258 entry or change it in certain ways. See <A HREF="#HDRWQ74">Protecting Group-Related Information</A>.
259 <P><DT><B><TT>group quota</TT>
260 </B><DD>This field indicates how many more groups a user is allowed to
261 create. It is set to 20 when a user entry is created. The
262 creation quota for machines or groups is meaningless because it not possible
263 to authenticate as a machine or group.
264 </DL>
265 <P><H3><A NAME="Header_125" HREF="auusg002.htm#ToC_125">Example: Listing Information about a Group</A></H3>
266 <A NAME="IDX1064"></A>
267 <P>The following example displays information about the group
268 <B>pat:accounting</B>, which includes members of the department that
269 <B>pat</B> manages. Notice that the group is self-owned, which
270 means that all of its members can administer it.
271 <PRE>   % <B>pts examine pat:accounting</B>
272    Name: pat:accounting, id: -673, owner: pat:accounting, creator: pat,
273      membership: 15, flags: S-M--, group quota: 0
274 </PRE>
275 <P>
276 <P><H3><A NAME="Header_126" HREF="auusg002.htm#ToC_126">Example: Listing Group Information about a User</A></H3>
277 <A NAME="IDX1065"></A>
278 <P>The following example displays group-related information about user
279 <B>pat</B>. The two most interesting fields are
280 <TT>membership</TT>, which shows that <B>pat</B> belongs to 12 groups,
281 and <TT>group quota</TT>, which shows that <B>pat</B> can create another
282 17 groups.
283 <PRE>  % <B>pts examine pat</B>
284    Name: pat, id: 1045, owner: system:administrators, creator: admin, 
285      membership: 12, flags: S-M--, group quota: 17
286 </PRE>
287 <HR><H2><A NAME="HDRWQ68" HREF="auusg002.htm#ToC_127">Creating Groups and Adding Members</A></H2>
288 <A NAME="IDX1066"></A>
289 <A NAME="IDX1067"></A>
290 <A NAME="IDX1068"></A>
291 <A NAME="IDX1069"></A>
292 <A NAME="IDX1070"></A>
293 <P>Use the <B>pts creategroup</B> command to create a group and the
294 <B>pts adduser</B> command to add members to it. Users and machines
295 can belong to groups, but other groups cannot.
296 <P>When you create a group, you normally become its owner
297 automatically. This means you alone can administer it: add and
298 remove members, change the group's name, transfer ownership of the group,
299 or delete the group entirely. If you wish, you can designate another
300 owner when you create the group, by including the <B>-owner</B> argument
301 to the <B>pts creategroup</B> command. If you assign ownership to
302 another group, the owning group must already exist and have at least one
303 member. You can also change a group's ownership after creating it
304 by using the <B>pts chown</B> command as described in <A HREF="#HDRWQ72">Changing a Group's Owner or Name</A>.
305 <P><H3><A NAME="HDRWQ69" HREF="auusg002.htm#ToC_128">To Create a Group</A></H3>
306 <A NAME="IDX1071"></A>
307 <A NAME="IDX1072"></A>
308 <P>Issue the <B>pts creategroup</B> command to create a group. Your
309 group-creation quota decrements by one for each group.
310 <PRE>   % <B>pts creategroup -name</B> &lt;<VAR>group&nbsp;name</VAR>>+ [<B>-owner</B> &lt;<VAR>owner&nbsp;of&nbsp;the&nbsp;group</VAR>>]
311 </PRE>
312 <P>where
313 <DL>
314 <P><DT><B>cg
315 </B><DD>Is an alias for <B>creategroup</B> (and <B>createg</B> is the
316 shortest acceptable abbreviation).
317 <P><DT><B>-name
318 </B><DD>Names each group to create. The name must have the following
319 format:
320 <P><VAR>owner_name</VAR><B>:</B><VAR>group_name</VAR>
321 <P>The <VAR>owner_name</VAR> prefix must accurately indicate the group's
322 owner. By default, you are recorded as the owner, and the
323 <VAR>owner_name</VAR> must be your AFS username. You can include the
324 <B>-owner</B> argument to designate another AFS user or group as the
325 owner, as long as you provide the required value in the <VAR>owner_name</VAR>
326 field: 
327 <A NAME="IDX1073"></A>
328 <A NAME="IDX1074"></A>
329 <UL>
330 <P><LI>If the owner is a user, it must be the AFS username.
331 <P><LI>If the owner is another regular group, it must match the owning
332 group's <VAR>owner_name</VAR> field. For example, if the owner is
333 the group <B>terry:associates</B>, the owner field must be
334 <B>terry</B>.
335 <P><LI>If the owner is a group without an <VAR>owner_name</VAR> prefix, it must be
336 the owning group's name.
337 </UL>
338 <P>The name can include up to 63 characters including the colon. Use
339 numbers and lowercase letters, but no spaces or punctuation characters other
340 than the colon.
341 <P><DT><B>-owner
342 </B><DD>Is optional and assigns ownership to a user other than yourself, or to a
343 group. If you specify a group, it must already exist and have at least
344 one member. (This means that to make a group self-owned, you must issue
345 the <B>pts chown</B> command after using this command to create the group,
346 and the <B>pts adduser</B> command to add a member. See <A HREF="#HDRWQ72">Changing a Group's Owner or Name</A>.)
347 <P>Do not name a machine as the owner. Because no one can authenticate
348 as a machine, there is no way to administer a group owned by a machine.
349 </DL>
350 <P><H3><A NAME="Header_129" HREF="auusg002.htm#ToC_129">Example:  Creating a Group</A></H3>
351 <P><B></B>
352 <A NAME="IDX1075"></A>
353 <P>In the following example user <B>terry</B> creates a group to include
354 all the other users in his work team, and then examines the new group
355 entry.
356 <PRE>   % <B>pts creategroup terry:team</B>
357    group terry:team has id -286
358    % <B>pts examine terry:team</B>
359    Name: terry:team, id: -286, owner: terry, creator: terry, 
360      membership: 0, flags: S----, group quota: 0.
361 </PRE>
362 <P><H3><A NAME="HDRWQ70" HREF="auusg002.htm#ToC_130">To Add Members to a Group</A></H3>
363 <A NAME="IDX1076"></A>
364 <A NAME="IDX1077"></A>
365 <A NAME="IDX1078"></A>
366 <A NAME="IDX1079"></A>
367 <P>Issue the <B>pts adduser</B> command to add one or more users to one or
368 more groups. You can always add members to a group you own (either
369 directly or because you belong to the owning group). If you belong to a
370 group, you can add members if its fourth privacy flag is the lowercase letter
371 <B>a</B>; see <A HREF="#HDRWQ74">Protecting Group-Related Information</A>.
372 <PRE>   % <B>pts adduser -user</B> &lt;<VAR>user&nbsp;name</VAR>><SUP>+</SUP> <B>-group</B> &lt;<VAR>group&nbsp;name</VAR>><SUP>+</SUP>
373 </PRE>
374 <P>You must add yourself to groups that you own, if that is
375 appropriate. You do not belong automatically just because you own the
376 group.
377 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If you already have a token when you are added to a group, you must issue the
378 <B>klog</B> command to reauthenticate before you can exercise the
379 permissions granted to the group on ACLs.
380 </TD></TR></TABLE>
381 <P>where
382 <DL>
383 <P><DT><B>-user
384 </B><DD>Specifies the username of each user to add to the groups named by the
385 <B>-group</B> argument. Groups cannot belong to other
386 groups.
387 <P><DT><B>-group
388 </B><DD>Names each group to which to add users.
389 </DL>
390 <P><H3><A NAME="Header_131" HREF="auusg002.htm#ToC_131">Example:  Adding Members to a Group</A></H3>
391 <A NAME="IDX1080"></A>
392 <P>In this example, user <B>terry</B> adds himself, <B>pat</B>,
393 <B>indira</B>, and <B>smith</B> to the group he just created,
394 <B>terry:team</B>, and then verifies the new list of members.
395 <PRE>   % <B>pts adduser -user terry pat indira smith -group terry:team</B>
396    % <B>pts members terry:team</B>
397    Members of terry:team (id: -286) are:
398      terry
399      pat
400      indira
401      smith
402 </PRE>
403 <HR><H2><A NAME="HDRWQ71" HREF="auusg002.htm#ToC_132">Removing Users from a Group and Deleting a Group</A></H2>
404 <A NAME="IDX1081"></A>
405 <A NAME="IDX1082"></A>
406 <A NAME="IDX1083"></A>
407 <A NAME="IDX1084"></A>
408 <A NAME="IDX1085"></A>
409 <A NAME="IDX1086"></A>
410 <A NAME="IDX1087"></A>
411 <A NAME="IDX1088"></A>
412 <P>You can use the following commands to remove groups and their
413 members:
414 <UL>
415 <P><LI>To remove a user from a group, use the <B>pts removeuser</B> command
416 <P><LI>To delete a group entirely, use the <B>pts delete</B> command
417 <P><LI>To remove deleted groups from ACLs, use the <B>fs cleanacl</B> command
418 </UL>
419 <P>When a group that you created is deleted, your group-creation quota
420 increments by one, even if you no longer own the group.
421 <P>When a group or user is deleted, its AFS ID appears on ACLs in place of its
422 AFS name. You can use the <B>fs cleanacl</B> command to remove
423 these obsolete entries from ACLs on which you have the <B>a</B>
424 (<B>administer</B>) permission.
425 <P><H3><A NAME="Header_133" HREF="auusg002.htm#ToC_133">To Remove Members from a Group</A></H3>
426 <A NAME="IDX1089"></A>
427 <A NAME="IDX1090"></A>
428 <P>Issue the <B>pts removeuser</B> command to remove one or more members
429 from one or more groups. You can always remove members from a group
430 that you own (either directly or because you belong to the owning
431 group). If you belong to a group, you can remove members if its fifth
432 privacy flag is the lowercase letter <B>r</B>; see <A HREF="#HDRWQ74">Protecting Group-Related Information</A>. (To display a group's owner, use the <B>pts
433 examine</B> command as described in <A HREF="#HDRWQ67">To Display A Group Entry</A>.)
434 <PRE>   % <B>pts removeuser -user</B>  &lt;<VAR>user&nbsp;name</VAR>><SUP>+</SUP>  <B>-group</B> &lt;<VAR>group&nbsp;name</VAR>><SUP>+</SUP>
435 </PRE>
436 <P>where
437 <DL>
438 <P><DT><B>-user
439 </B><DD>Specifies the username of each user to remove from the groups named by the
440 <B>-group</B> argument.
441 <P><DT><B>-group
442 </B><DD>Names each group from which to remove users.
443 </DL>
444 <P><H3><A NAME="Header_134" HREF="auusg002.htm#ToC_134">Example:  Removing Group Members</A></H3>
445 <A NAME="IDX1091"></A>
446 <P>The following example removes user <B>pat</B> from both the
447 <B>terry:team</B> and <B>terry:friends</B> groups.
448 <PRE>   % <B>pts removeuser  pat -group terry:team terry:friends</B>
449 </PRE>
450 <P><H3><A NAME="Header_135" HREF="auusg002.htm#ToC_135">To Delete a Group</A></H3>
451 <A NAME="IDX1092"></A>
452 <A NAME="IDX1093"></A>
453 <P>Issue the <B>pts delete</B> command to delete a group. You can
454 always delete a group that you own (either directly or because you belong to
455 the owning group). To display a group's owner, use the <B>pts
456 examine</B> command as described in <A HREF="#HDRWQ67">To Display A Group Entry</A>.
457 <PRE>   % <B>pts delete</B> &lt;<VAR>user&nbsp;or&nbsp;group&nbsp;name&nbsp;or&nbsp;id</VAR>><SUP>+</SUP>
458 </PRE>
459 <P>where <VAR>user or group name or id</VAR> specifies the name or AFS UID of
460 each user, or the name or AFS GID of each group, to delete. If
461 identifying a group by its AFS GID, precede the GID with a hyphen
462 (<B>-</B>) to indicate that it is a negative number.
463 <P><H3><A NAME="Header_136" HREF="auusg002.htm#ToC_136">Example:  Deleting a Group</A></H3>
464 <P><B></B>
465 <A NAME="IDX1094"></A>
466 <P>In the following example, the group <B>terry:team</B> is
467 deleted.
468 <PRE>   % <B>pts delete terry:team</B>
469 </PRE>
470 <P><H3><A NAME="Header_137" HREF="auusg002.htm#ToC_137">To Remove Obsolete ACL Entries</A></H3>
471 <A NAME="IDX1095"></A>
472 <A NAME="IDX1096"></A>
473 <P>Issue the <B>fs cleanacl</B> command to remove obsolete entries from
474 ACLs after the corresponding user or group has been deleted.
475 <PRE>   % <B>fs cleanacl</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
476 </PRE>
477 <P>where <VAR>dir/file path</VAR> name each directory for which to clean the
478 ACL. If you omit this argument, the current working directory's
479 ACL is cleaned.
480 <P><B></B>
481 <A NAME="IDX1097"></A>
482 <P><H3><A NAME="Header_138" HREF="auusg002.htm#ToC_138">Example:  Removing an Obsolete ACL Entry</A></H3>
483 <P>After the group <B>terry:team</B> is deleted, its AFS GID
484 (-286) appears on ACLs instead of its name. In this example, user
485 <B>terry</B> cleans it from the ACL on the plans directory in his home
486 directory.
487 <PRE>   % <B>fs listacl plans</B>
488    Access list for plans is
489    Normal rights:
490      terry rlidwka
491      -268 rlidwk
492      sam rliw
493    % <B>fs cleanacl plans</B>
494    % <B>fs listacl plans</B>
495    Access list for plans is
496    Normal rights:
497      terry rlidwka
498      sam rliw
499 </PRE>
500 <HR><H2><A NAME="HDRWQ72" HREF="auusg002.htm#ToC_139">Changing a Group's Owner or Name</A></H2>
501 <A NAME="IDX1098"></A>
502 <A NAME="IDX1099"></A>
503 <A NAME="IDX1100"></A>
504 <A NAME="IDX1101"></A>
505 <P>To change a group's owner, use the <B>pts chown</B>
506 command. To change its name, use the <B>pts rename</B>
507 command.
508 <P>You can change the owner or name of a group that you own (either directly
509 or because you belong to the owning group). You can assign group
510 ownership to another user, another group, or the group itself. If you
511 are not already a member of the group and need to be, use the <B>pts
512 adduser</B> command before transferring ownership, following the
513 instructions in <A HREF="#HDRWQ70">To Add Members to a Group</A>.
514 <P>The <B>pts chown</B> command automatically changes a group's
515 <VAR>owner_name</VAR> prefix to indicate the new owner. If the new owner
516 is a group, only its <VAR>owner_name</VAR> prefix is used, not its entire
517 name. However, the change in <VAR>owner_name</VAR> prefix command does
518 not propagate to any groups owned by the group whose owner is changing.
519 If you want their <VAR>owner_name</VAR> prefixes to indicate the correct owner,
520 you must use the <B>pts rename</B> command.
521 <P>Otherwise, you normally use the <B>pts rename</B> command to change
522 only the <VAR>group_name</VAR> part of a group name (the part that follows the
523 colon). You can change the <VAR>owner_name</VAR> prefix only to reflect
524 the actual owner.
525 <P><H3><A NAME="HDRWQ73" HREF="auusg002.htm#ToC_140">To Change a Group's Owner</A></H3>
526 <A NAME="IDX1102"></A>
527 <A NAME="IDX1103"></A>
528 <P>Issue the <B>pts chown</B> command to change a group's
529 name.
530 <PRE>   % <B>pts chown</B>  &lt;<VAR>group&nbsp;name</VAR>> &lt;<VAR>new&nbsp;owner</VAR>>
531 </PRE>
532 <P>where
533 <DL>
534 <P><DT><B><VAR>group name</VAR>
535 </B><DD>Specifies the current name of the group to which to assign a new
536 owner.
537 <P><DT><B><VAR>new owner</VAR>
538 </B><DD>Names the user or group that is to own the group.
539 </DL>
540 <P><H3><A NAME="Header_141" HREF="auusg002.htm#ToC_141">Example:  Changing a Group's Owner to Another User</A></H3>
541 <A NAME="IDX1104"></A>
542 <P>In the following example, user <B>pat</B> transfers ownership of the
543 group <B>pat:staff</B> to user <B>terry</B>. Its name
544 changes automatically to <B>terry:staff</B>, as confirmed by the
545 <B>pts examine</B> command.
546 <PRE>   % <B>pts chown pat:staff terry</B>
547    % <B>pts examine terry:staff</B> 
548    Name: terry:staff, id: -534, owner: terry, creator: pat, 
549      membership: 15, flags: SOm--, group quota: 0.
550 </PRE>
551 <P><H3><A NAME="Header_142" HREF="auusg002.htm#ToC_142">Example:  Changing a Group's Owner to Itself</A></H3>
552 <A NAME="IDX1105"></A>
553 <P>In the following example, user <B>terry</B> makes the
554 <B>terry:team</B> group a self-owned group. Its name does not
555 change because its <VAR>owner_name</VAR> prefix is already
556 <B>terry</B>.
557 <PRE>   % <B>pts chown terry:team terry:team</B>
558    % <B>pts examine terry:team</B>
559    Name: terry:team, id: -286, owner: terry:team, creator: terry, 
560      membership: 6, flags: SOm--, group quota: 0.
561 </PRE>
562 <P><H3><A NAME="Header_143" HREF="auusg002.htm#ToC_143">Example: Changing a Group's Owner to a Group</A></H3>
563 <P>In this example, user <B>sam</B> transfers ownership of the group
564 <B>sam:project</B> to the group <B>smith:cpa</B>.
565 Its name changes automatically to <B>smith:project</B>, because
566 <B>smith</B> is the <VAR>owner_name</VAR> prefix of the group that now owns
567 it. The <B>pts examine</B> command displays the group's status
568 before and after the change.
569 <PRE>   % <B>pts examine sam:project</B>
570    Name: sam:project, id: -522, owner: sam, creator: sam, 
571      membership: 33, flags: SOm--, group quota: 0.
572    % <B>pts chown sam:project smith:cpa</B>
573    % <B>pts examine smith:project</B>
574    Name: smith:project, id: -522, owner: smith:cpa, creator: sam, 
575      membership: 33, flags: SOm--, group quota: 0.
576 </PRE>
577 <P><H3><A NAME="Header_144" HREF="auusg002.htm#ToC_144">To Change a Group's Name</A></H3>
578 <A NAME="IDX1106"></A>
579 <A NAME="IDX1107"></A>
580 <P>Issue the <B>pts rename</B> command to change a group's
581 name.
582 <PRE>   % <B>pts rename</B>  &lt;<VAR>old&nbsp;name</VAR>> &lt;<VAR>new&nbsp;name</VAR>>
583 </PRE>
584 <P>where
585 <DL>
586 <P><DT><B><VAR>old name</VAR>
587 </B><DD>Specifies the group's current name.
588 <P><DT><B><VAR>new name</VAR>
589 </B><DD>Specifies the complete new name to assign to the group. The
590 <VAR>owner_name</VAR> prefix must correctly indicate the group's
591 owner.
592 </DL>
593 <P><H3><A NAME="Header_145" HREF="auusg002.htm#ToC_145">Example:  Changing a Group's <VAR>group_name</VAR> Suffix</A></H3>
594 <A NAME="IDX1108"></A>
595 <P>The following example changes the name of the
596 <B>smith:project</B> group to
597 <B>smith:fiscal-closing</B>. The group's
598 <VAR>owner_name</VAR> prefix remains <B>smith</B> because its owner is not
599 changing.
600 <PRE>   % <B>pts examine smith:project</B>
601    Name: smith:project, id: -522, owner: smith:cpa, creator: sam, 
602      membership: 33, flags: SOm--, group quota: 0.
603    % <B>pts rename smith:project smith:fiscal-closing</B>
604    % <B>pts examine smith:fiscal-closing</B>
605    Name: smith:fiscal-closing, id: -522, owner: smith:cpa, creator: sam, 
606      membership: 33, flags: SOm--, group quota: 0.
607 </PRE>
608 <P><H3><A NAME="Header_146" HREF="auusg002.htm#ToC_146">Example: Changing a Group's <VAR>owner_name</VAR> Prefix</A></H3>
609 <P>In a previous example, user <B>pat</B> transferred ownership of the
610 group <B>pat:staff</B> to user <B>terry</B>. Its name
611 changed automatically to <B>terry:staff</B>. However, a group
612 that <B>terry:staff</B> owns is still called
613 <B>pat:plans</B>, because the change to a group's
614 <VAR>owner_name</VAR> that results from the <B>pts chown</B> command does
615 not propagate to any groups it owns. In this example, a member of
616 <B>terry:staff</B> uses the <B>pts rename</B> command to change
617 the name to <B>terry:plans</B> to reflect its actual
618 ownership.
619 <PRE>   % <B>pts examine pat:plans</B> 
620    Name: pat:plans, id: -535, owner: terry:staff, creator: pat, 
621      membership: 8, flags: SOm--, group quota: 0.
622    % <B>pts rename pat:plans terry:plans</B>
623    % <B>pts examine terry:plans</B> 
624    Name: terry:plans, id: -535, owner: terry:staff, creator: pat, 
625      membership: 8, flags: SOm--, group quota: 0.
626 </PRE>
627 <HR><H2><A NAME="HDRWQ74" HREF="auusg002.htm#ToC_147">Protecting Group-Related Information</A></H2>
628 <A NAME="IDX1109"></A>
629 <A NAME="IDX1110"></A>
630 <A NAME="IDX1111"></A>
631 <A NAME="IDX1112"></A>
632 <A NAME="IDX1113"></A>
633 <A NAME="IDX1114"></A>
634 <A NAME="IDX1115"></A>
635 <A NAME="IDX1116"></A>
636 <P>A group's <I>privacy flags</I> control who can administer it in
637 various ways. The privacy flags appear in the <TT>flags</TT> field of
638 the output from the <B>pts examine</B> command command; see <A HREF="#HDRWQ67">To Display A Group Entry</A>. To set the privacy flags for a group you own, use
639 the <B>pts setfields</B> command as instructed in <A HREF="#HDRWQ75">To Set a Group's Privacy Flags</A>.
640 <P><H3><A NAME="HDRPRIVACY-FLAGS" HREF="auusg002.htm#ToC_148">Interpreting the Privacy Flags</A></H3>
641 <P>The five privacy flags always appear, and always
642 must be set, in the following order:
643 <DL>
644 <P><DT><B>s
645 </B><DD>Controls who can issue the <B>pts examine</B> command to display the
646 entry.
647 <P><DT><B>o
648 </B><DD>Controls who can issue the <B>pts listowned</B> command to list the
649 groups that a user or group owns.
650 <P><DT><B>m
651 </B><DD>Controls who can issue the <B>pts membership</B> command to list the
652 groups a user or machine belongs to, or which users or machines belong to a
653 group.
654 <P><DT><B>a
655 </B><DD>Controls who can issue the <B>pts adduser</B> command to add a user or
656 machine to a group.
657 <P><DT><B>r
658 </B><DD>Controls who can issue the <B>pts removeuser</B> command to remove a
659 user or machine from a group.
660 </DL>
661 <P>Each flag can take three possible types of values to enable a different set
662 of users to issue the corresponding command:
663 <UL>
664 <P><LI>A hyphen (<B>-</B>) means that the group's owner can issue the
665 command, along with the administrators who belong to the
666 <B>system:administrators</B> group.
667 <P><LI>The lowercase version of the letter means that members of the group can
668 issue the command, along with the users indicated by the hyphen.
669 <P><LI>The uppercase version of the letter means that anyone can issue the
670 command.
671 </UL>
672 <P>For example, the flags <TT>SOmar</TT> on a group entry indicate that
673 anyone can examine the group's entry and list the groups that it owns,
674 and that only the group's members can list, add, or remove its
675 members.
676 <P>The default privacy flags for groups are <TT>S-M--</TT>, meaning that
677 anyone can display the entry and list the members of the group, but only the
678 group's owner and members of the <B>system:administrators</B>
679 group can perform other functions.
680 <P><H3><A NAME="HDRWQ75" HREF="auusg002.htm#ToC_149">To Set a Group's Privacy Flags</A></H3>
681 <A NAME="IDX1117"></A>
682 <A NAME="IDX1118"></A>
683 <P>Issue the <B>pts setfields</B> command to set the privacy flags on one
684 or more groups.
685 <PRE>   % <B>pts setfields -nameorid</B> &lt;<VAR>user&nbsp;or&nbsp;group&nbsp;name&nbsp;or&nbsp;id</VAR>><SUP>+</SUP>
686                    <B>-access</B> &lt;<VAR>set&nbsp;privacy&nbsp;flags</VAR>>
687 </PRE>
688 <P>where
689 <DL>
690 <P><DT><B>-nameorid
691 </B><DD>Specifies the name or AFS GID of each group for which to set the privacy
692 flags. If identifying a group by its AFS GID, precede the GID with a
693 hyphen (<B>-</B>) to indicate that it is a negative number.
694 <P><DT><B>-access
695 </B><DD>Specifies the privacy flags to set for each group. Observe the
696 following rules:
697 <UL>
698 <P><LI>Provide a value for all five flags in the order <B>somar</B>.
699 <P><LI>Set the first flag to lowercase <B>s</B> or uppercase <B>S</B>
700 only.
701 <P><LI>Set the second flag to the hyphen (<B>-</B>) or uppercase <B>O</B>
702 only. For groups, AFS interprets the hyphen as equivalent to lowercase
703 <B>o</B> (that is, members of a group can always list the groups that it
704 owns).
705 <P><LI>Set the third flag to the hyphen (<B>-</B>), lowercase <B>m</B>,
706 or uppercase <B>M</B>.
707 <P><LI>Set the fourth flag to the hyphen (<B>-</B>), lowercase <B>a</B>,
708 or uppercase <B>A</B>. The uppercase <B>A</B> is not a secure
709 choice, because it permits anyone to add members to the group.
710 <P><LI>Set the fifth flag to the hyphen (<B>-</B>) or lowercase <B>r</B>
711 only.
712 </UL>
713 </DL>
714 <P><H3><A NAME="Header_150" HREF="auusg002.htm#ToC_150">Example:  Setting a Group's Privacy Flags</A></H3>
715 <A NAME="IDX1119"></A>
716 <P>The following example sets the privacy flags on the
717 <B>terry:team</B> group to set the indicated pattern of
718 administrative privilege.
719 <PRE>   % <B>pts setfields terry:team -access SOm--</B>
720   
721 </PRE>
722 <UL>
723 <P><LI>Everyone can issue the <B>pts examine</B> command to display general
724 information about it (uppercase <B>S</B>).
725 <P><LI>Everyone can issue the <B>pts listowned</B> command to display the
726 groups it owns (uppercase <B>O</B>).
727 <P><LI>The members of the group can issue the <B>pts membership</B> command
728 to display the group's members (lowercase <B>m</B>).
729 <P><LI>Only the group's owner, user <B>terry</B>, can issue the <B>pts
730 adduser</B> command to add members (the hyphen).
731 <P><LI>Only the group's owner, user <B>terry</B>, can issue the <B>pts
732 removeuser</B> command to remove members (the hyphen).
733 </UL>
734 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg007.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auusg009.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
735 <!-- Begin Footer Records  ========================================== -->
736 <P><HR><B> 
737 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved 
738 </B> 
739 <!-- End Footer Records  ============================================ -->
740 <A NAME="Bot_Of_Page"></A>
741 </BODY></HTML>