![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to 3.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / notes / doc|
Return to 3.1 CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / notes / doc |
1.1 root 1: .ls 1
2: .ch "Managing Notesfiles"
3:
4: The notesfile system is installed by a user who is known as the
5: ``owner'' of the notesfiles (UIUCDCS uses user ``notes'').
6: This user can create, delete, rename, and initiate networking of notesfiles.
7: Each notesfile is assigned a set of ``directors'' (who may or may not be
8: associated with owner of notesfiles). The directors have special privileges
9: for managing the notesfile (see below).
10: The ``owner'' rarely manages the day to day aspects of a notesfile,
11: although he has director, read, write and response privileges to
12: all notesfiles for
13: handling emergencies and failures.
14:
15: .se "Director Options"
16:
17: The director can:
18:
19: .bx
20: .ix
21: Change the access permissions.
22: .ix
23: Write the policy note.
24: .ix
25: Change the notesfile title and director message.
26: .ix
27: Open or close the notesfile.
28: .ix
29: Allow the notesfile to be networked.
30: .ix
31: Permit or restrict anonymous notes.
32: .ix
33: Compress the notesfile.
34: .ix
35: Change the notesfile's archival parameters.
36: .ix
37: Delete notes and responses.
38: .ix
39: Toggle director message on any note or response.
40: .ex
41:
42: The director can delete notes or toggle the director message
43: above them while reading the notes.
44: Access other options
45: by typing ``d'' on the index page. A display like this results:
46: .KS
47: .nf
48:
49: .ce 99
50: Workstation Discussion
51: *** Your Director Message Here ***
52:
53: .ce 0
54: .ta 3i
55: (a) Anonymous: ON Policy Note Exists: YES
56: (o) Notesfile: OPEN Next note in slot: 1
57: (n) Networked: YES Deleted Notes (holes): 0
58: (A) Is Archive: NO Deleted Responses (holes): 0
59: (e) Expiration Threshold: Default
60: (E) Expiration Action: ARCHIVE
61: (D) Archive with Dirmsg: NOCARE
62: (W) Working Set Size: Default
63: (l) Maximum Text/Article: 65000 bytes
64: .TA
65:
66:
67:
68:
69:
70:
71: Option:
72:
73: .ce 99
74: = = = = = = = = = = = = = = = = = =
75: .ce 0
76: .fi
77: .KE
78:
79: Options available on this page include: access lists, policy
80: note writing, title & director messages, open/close notesfile,
81: network enabling, anonymous notes, notesfile compress, and delete
82: a list of notes.
83:
84: .ss "Access Lists"
85:
86: The notesfile system allows directors to allow or restrict access
87: to each notesfile.
88: The access list can allow or deny read, write, respond, and director
89: options to any user, group, or system.
90: Type ``p'' (``permissions'') on the director options page
91: to enter the access list editor.
92: The system prompts for an option:
93: ``m'' to modify an extant entry, ``d'' to delete
94: an entry, ``i'' to insert a new entry, ``r'' to replot the list,
95: ``q'' to quit editing the access list, and
96: capital ``Q'' to quit editing the access list and IGNORE ANY CHANGES MADE.
97: Delete or modify entries by entry number. Scroll the entries using ``+'' and
98: ``-''.
99:
100: After typing ``i'' to insert a new entry,
101: the system prompts for a user type
102: (``u'' for user, ``g'' for group, ``s'' for system).
103: The system then prompts for the name of the user, group, or system.
104: (Users and groups must be valid names)
105: The default access options
106: are then displayed: read, write, answer (for responses). Use the keys
107: ``r'', ``w'', ``a'', and ``d'' to toggle the read, write, answer, and director
108: privileges respectively. Some options automatically
109: enable others (e.g., ``w'' for writing automatically enables ``a'' for answering).
110: It is not possible to remove answer access while write access is enabled.
111: The ``n'' key will remove all privileges (``no access'').
112: Type return (or ``q'') when the correct options have been entered.
113: The system prompts for another user. Press return at the prompt to exercise
114: other access list options.
115:
116: The access machinery checks user names before checking
117: group names.
118: If user ``john'' explicitly has no
119: access but his group does, he will nevertheless be denied access to the file.
120: If there is no explicit entry for user ``john'', a check is made for
121: permissions granted to his group(s).
122: (n.b.: an entry for user ``Other'' will match all users,
123: circumventing group permissions.
124: The behavior typically desired can be achieved with a
125: group ``Other'' just as well.)
126:
127: If no explicit user entry exists, a search for group permissions
128: is initiated.
129: Users can belong to more than one group
130: (although kernels such as Version 7 only allow one at a time)
131: and the notesfile code checks each of the user's groups.
132: If permissions for several of these groups exist,
133: the user is given the inclusive OR of the several permissions.
134: If none of the user's groups are given permission, a
135: default permission specified by group ``Other'' is usually
136: assigned.
137: The ``Other'' entry matches when none of the other group entries
138: have matched.
139: This entry can be deleted, in which case no access is granted.
140:
141: The current implementation of system access
142: enforcement is naive.
143: The network software will send to a system only if it has read permission.
144: Reception allows intermediaries
145: to pass on notes even if they are not allowed write access to the notesfile;
146: the access permission is determined from the originating system of each note
147: or response
148: instead of the site actually delivering the article.
149: The name ``Other'' (capital ``O'') matches any system name not
150: mentioned explicitly.
151:
152: Many notesfiles allow several users and groups to have
153: read/write access,
154: a single user to have director access
155: (in addition to the notesfile ``owner''),
156: and all other users no access.
157:
158: When a notesfile is first created, a default access
159: list is created.
160: The notesfile ``owner'' is made director, group ``Other''
161: and system ``Other'' are both given read/write access
162: to the notesfile.
163: If the file ``/usr/spool/notes/.utilities/access-template''
164: exists, it contains a list of access-rights to add to
165: the new notesfile's access list.
166: The file contains lines of access-rights in the format used
167: by the nfaccess program.
168: Access-rights look like ``user:essick=drwa'';
169: for more information on the format of these entries,
170: see the man(I) page for nfaccess.
171:
172: .ss "Policy Note"
173:
174: Type ``w'' (``write policy'') on the director option page to write a policy
175: note (just like writing any other note).
176:
177: .ss "Title & Director Messages"
178:
179: Change the notesfile title with ``t'', the director message with ``m''.
180: The
181: system prompts for a new message.
182: Typing only a carriage return will not change the old message.
183:
184: .ss "Open/Close"
185:
186: Type ``o'' (``open'') to toggle the availability of the notesfile (subject to
187: the access list).
188: Closed notesfiles are unavailable to non-directors.
189:
190: .ss "Network Options"
191:
192: Type ``n'' (``network'') to toggle the availability of the notesfile
193: for networking.
194: Arrangements must be made with the notesfile system ``owner'' to do the network
195: transfers.
196:
197: .ss "Anonymous Notes"
198:
199: Type ``a'' (``anonymous'') to toggle the availability of
200: anonymous notes in the notesfile.
201: The availability of the anonymous option may provoke slanderous
202: attacks from users
203: (whose anonymity is completely protected).
204:
205: .ss "Compression"
206:
207: Type ``c'' (``compress'') to compress the notesfile. As notes
208: are deleted, their text and index space is not reclaimed. This command
209: reclaims the space. The notesfile must be closed. On a VAX 11/780,
210: 20 seconds of real time (on a slightly loaded system) is required to
211: reclaim the space of a notesfile with 50 remaining notes
212: (compression time is dependent on remaining notes).
213: Notesfiles should be compressed whenever many of their notes have been
214: deleted.
215: The notesfile archiver ``nfarchive'' and cron(8) can be used to automate this
216: process.
217:
218: The director's option page displays a count of ``holes''
219: left by deleted notes and responses.
220: This can be used as an indication of how much wasted space is within
221: the notesfile.
222:
223: .ss "Expiration Threshold"
224:
225: The `e' command allows a notesfile director to
226: modify the notesfile's expiration threshold.
227: Possible values include specific numbers of days, `default'
228: and `never'.
229: The value can be left unchanged by not specifying a
230: new value.
231: The `default' value is assigned to new notesfiles;
232: directors can change it as needed.
233:
234: The notesfile archiving program (nfarchive) examines the
235: expiration threshold of each notesfile it processes.
236: This threshold determines how long a note string must be inactive
237: before it is eligible for archival.
238: The `Default' expiration threshold uses the expiration time
239: specified on the `nfarchive' command line;
240: this is usually 2 weeks.
241: Specific ages can be specified.
242: The age specified in the notesfile overrides the value
243: on the `nfarchive' command line.
244: The `Never' threshold tells `nfarchive' that this notesfile is
245: not to be archived.
246:
247: .ss "Working Set Size"
248:
249: Each notesfile contains a working set of notes.
250: The working set is the number of notes left in the notesfile
251: by the nfarchive program.
252: When nfarchive runs, it determines a maximum number of notes
253: to delete.
254: This number is the number of notes written in the notesfile
255: minus the number of ``holes'' caused by deletions minus
256: the working set size.
257: Nfarchive will leave a ``working set size'' of notes in
258: the notesfile;
259: if fewer notes existed in the notesfile, no notes are
260: archived.
261:
262: The working set size can be changed by the `s' command
263: from the director page.
264: Possible values include ``default'' and specific numbers.
265: ``Default'' specifies that the value supplied during
266: the nfarchive run is to be used;
267: explicit values in the notesfile always override values
268: specified on the nfarchive command line.
269:
270: .ss "Expiration Action"
271:
272: Each notesfile can decide on the destination of expired
273: notestrings.
274: The expiration action field takes one of the values
275: ``Default'', ``Archive'' or ``Delete''.
276: Archive and delete specify that expired notes are to be
277: archived and deleted respectively.
278: The default entry specifies that the expiration action should
279: follow that specified on the nfarchive command line.
280:
281: .ss "Expire With Director Message"
282:
283: Notesfiles can decide how to expire based on director
284: message status individually.
285: This option can assume four values:
286: ``Default'',
287: ``Nocare'',
288: ``On'',
289: and
290: ``Off''.
291: The on and off values specify that only notes with the
292: director message on or off respectively are eligible for
293: expiration.
294: The nocare value specifies that the director message status
295: is not checked; both director and non-director marked notes
296: are eligible for expiration.
297: Select the default entry to use the value of this parameter
298: as specified on the nfarchive command line.
299:
300: .ss "Maximum Text per Article"
301:
302: The notesfile system imposes limits on the size of
303: each article. Earlier versions restricted articles to 64 kbytes;
304: the current version provides for articles up to 4 Gigabytes.
305: A constant is used to determine
306: the actual maximum allowed per article.
307:
308: Each notesfile can select a maximum text length per
309: article.
310: This limit is not allowed to exceed the hard-coded limit
311: (currently 3 Mbytes).
312: Articles exceeding this limit are truncated and a message
313: detailing the count of excess bytes and the system responsible
314: for truncating the text is appended.
315:
316: Initially the maximum text length is set to the
317: highest permissible value.
318: One reason for lowering the limit is to meet restrictions
319: on the size of network transfers.
320:
321: .ss "Deleting and Un-Deleting Many Articles"
322:
323: Type ``z'' (``zap'') to delete many notes (and their
324: responses) quickly.
325: Enter a list of note numbers or note ranges (aa-bb) separated by spaces.
326: Confirm the command with ``y''; other responses will abort the command.
327: It is economical and prudent to compress the notesfile
328: shortly thereafter.
329: Note that deleting notes in a networked notesfile makes those notes
330: unavailable to those who poll your system for new notes and responses.
331:
332: The ``u'' (undelete) command performs the opposite function
333: of the ``z'' command.
334: This command allows you to specify a list of note strings to
335: be un-deleted.
336: When prompted, the director shoul supply the note numbers he wishes
337: to re-activate.
338: The specified notes are re-activated and can be viewed as before.
339: This command is only effective until a compression of the notesfile;
340: after that time the notes are no longer present in the notesfile.
341:
342: .ss "Director Options for Notes"
343:
344: Directors may put a ``director message'' above any note they write.
345: There is one single line director message for each notesfile. Typical
346: director messages
347: are: ``New Policy'', ``*** This problem fixed or ignored ***'',
348: or ``-- Eat Flaming Death Fascist Pigs --''.
349: Directors can also toggle the director message on
350: a note being
351: read (``d'' for ``director message'').
352: A director can delete a note (and all its
353: responses) or any response while reading the text of the note or response
354: by typing ``Z'' (``zap this one'') and confirming with ``y''.
355:
356: .ss "Default Sequencer Lists"
357:
358: Some users never set up an ``NFSEQ'' environment variable
359: specifying the notesfile they wish to see.
360: The file ``/usr/spool/notes/.utilities/Dflt-Seq'' contains a
361: default list of notesfiles.
362: Users without an ``NFSEQ'' variable receive the notesfiles listed
363: in this file.
364: The file can be changed at anytime and will take effect with
365: the next ``autoseq'' by a user.
366:
367: .se "Creation & Deletion of Notesfiles"
368:
369: Only the ``owner'' of the notesfile system can create notesfiles.
370: Create notesfiles with the mknf command:
371:
372: mknf [ -aon ] topic1 [ ... ]
373:
374: The created notesfiles have default status of
375: closed, non-networked, and
376: no anonymous notes permitted.
377: Specify -a to permit anonymous notes in the new notesfiles.
378: Use -o to have the notesfiles marked open for general use and
379: the -n option to enable the notesfiles' network availability.
380: These status flags can all be modified from the directors page at later
381: times.
382:
383: Delete notesfiles with rmnf:
384:
385: rmnf [ -f ] topic1 [ ... ]
386:
387: Each notesfile to be removed must be verified with ``y'' after a
388: prompt -- anything else will leave that notesfile intact.
389: Use the -f option to blindly remove notesfiles;
390: the verification step is bypassed when ``rmnf'' is invoked
391: with the -f option.
392:
393: The file /usr/spool/notes/.utilities/avail.notes contains
394: a list of the public notesfiles.
395: The notesfile owner should update this file when he creates
396: new notesfiles;
397: this file is not automatically updated by ``mknf'' and ``rmnf''.
398: The contents and format of the file are at the discretion of the
399: notesfile system owner.
400:
401: .se "Intersystem Notesfiles"
402:
403: The notesfile system provides for intersystem notesfiles
404: in an arbitrary connected network.
405: Copies of a shared notesfile must exist on each
406: of the systems wishing to read notes for that notesfile.
407: The contents are kept in synchrony through occasional exchanges
408: over a network (UIUCDCS uses both uucp and tcp/ip).
409: Notesfiles to be shared must have their ``network status'' enabled (see
410: director options).
411:
412: Duplication of notes and responses is prevented by the use of
413: unique identifiers.
414: Each note and response in a notesfile is assigned a unique number.
415: The networking software checks each note as it arrives to
416: see if a copy already exists.
417: In the event of duplication, the extra copy is discarded and
418: the fact is logged in the statistics and the network log.
419:
420: In the (hopefully rare) event that a response arrives at a
421: system before the base note does, the network reception program will
422: generate a ``foster parent'' for the orphaned response.
423: When the true parent arrives,
424: the foster parent will be overwritten.
425: A count of orphaned responses received is kept and available
426: through use of the nfstats program (see section 4.4).
427:
428: .ss "Transmitting Notesfile Updates"
429:
430: The nfxmit program gathers the new notes and responses in specified
431: notesfiles and sends them to a specified site.
432: The notesfile ``owner'' must occasionally enter the following command (or
433: have it entered for him by cron)
434: to update remote notesfiles with new notes and receive new remote
435: notes:
436:
437: nfxmit -dsitename [-t datespec] [-r] [-a] [-f file] topic1 [...]
438:
439: The ``sitename'' is the name of the remote site
440: to receive the new notes.
441: The remote site should have notesfiles matching those specified
442: by the topic1 parameter.
443: For remote notesfiles with different names, see the section below on
444: Name Mapping.
445:
446: The optional -t specifies that all notes and responses
447: since that date should be sent (normally -t is omitted and the notesfile
448: system sends only new notes and responses).
449:
450: The -r option specifies that the remote notes system
451: should not only receive the current changes but also reply in kind.
452: This is useful if the remote system does not automatically run the
453: nfxmit program.
454:
455: The -a option specifies that articles inserted
456: from the news(I) system
457: are to be sent also. Normally these articles are not sent because the
458: receiver probably has them; the primary use of this switch is for sites
459: that do not run news(I).
460:
461: Using the -f switch tells nfxmit
462: to read the file specified for a list
463: of notesfiles to transmit;
464: multiple -f parameters are permitted and can be freely intermixed
465: with `topic' parameters.
466: Notesfile name pattern matching is
467: performed on both `topic' parameters and
468: the entries in a file specified by the -f option.
469:
470: Nfxmit uses uux(1) as a transport and remote execution
471: mechanism. Connections using different protocols and mechanisms
472: can be selected in the file ``/usr/spool/notes/.utilities/net.how'';
473: its format is described in the section ``Non-Standard Links''.
474: Uux typically permits a limited set of commands to be executed
475: remotely.
476: The file ``uuxqt.c'' in the UUCP source code contains a list of
477: acceptable commands; this file should be edited to include the
478: ``nfrcv'' program.
479:
480: .ss "Network Transaction Log"
481:
482: The network software maintains a log of all transactions,
483: including time, date, number of notes and responses transferred, direction
484: of transfer,
485: and number of notes replicated by transfer.
486: This log is placed in a file called `net.log' and resides in the
487: notesfile utility directory (by default: /usr/spool/notes/.utilities).
488:
489: This file will grow without bounds.
490: Occasional pruning is a good idea.
491: There is no vital information stored in this file;
492: its purpose is to provide a network audit trail.
493:
494: .ss "Non-Standard Links"
495:
496: Some systems will be unable to keep the notesfile network
497: software in a public directory (such as /usr/bin).
498: Other sites will have non-uucp links.
499: The `net.how' file is for these cases. `Net.how' is
500: kept in the notesfile utility
501: directory (/usr/spool/notes/.utilities)
502: and
503: contains information on linking to remote systems.
504: Entries in the file are made for systems with non-standard links
505: and
506: have the following format:
507:
508: system:direction:protocol::command string
509:
510: The system field contains the name of the remote system.
511: The direction field
512: contains either an `x' or `r' (no quotes) and specifies the direction
513: that the line is for.
514: An `x' specifies that the command string is for sending notes to the
515: remote site; an `r' specifies that the command string is used in
516: coercing the remote system to send its new notes and responses back.
517: Lines beginning with a `#' are comment lines and ignored by the notesfile
518: code.
519:
520: The protocol field is either empty or contains an integer
521: value. An empty field indicates protocol 0.
522: Currently only protocols 0 and 1 are supported.
523: The notesfile receiving programs automatically switch between
524: protocols.
525:
526: The command string is a printf control string (without quotes)
527: with two `%s'
528: entries.
529: The first is for filling in the name of the notesfile, the second is
530: for the local system name.
531: Many entries in the `net.how' file will be to place
532: different paths on the `nfrcv' and `nfxmit' commands.
533: The default command line is:
534:
535: uux -z - system\\!nfrcv %s %s
536:
537: for the `x' entry and for the `r' entry:
538:
539: uux system\\!nfxmit %s -d%s
540:
541: In the following sample from our net.how file, the host
542: ``uicsovax'' is connected via UUCP and the notesfile networking
543: programs live in non-standard directories.
544: The host ``etherhost'' is reachable over a local network and the
545: Berkeley ``rsh'' commands can be used to ship data between
546: the local host and ``etherhost''.
547:
548: .nf
549: uicsovax:x:::uux - uicsovax!/mnt/dcs/essick/.commands/nfrcv %s %s
550: uicsovax:r:::uux uicsovax!/mnt/dcs/essick/.commands/nfxmit %s -d%s
551: etherhost:x:::rsh etherhost /usr/bin/nfrcv %s %s
552: etherhost:r:::rsh etherhost /usr/bin/nfxmit %s -d%s
553: .fi
554:
555:
556: .ss "Notesfile Name Mapping"
557:
558: To provide flexibility in the naming of notesfile across systems,
559: the network software looks in the
560: directory /usr/spool/notes/.utilities/net.aliases
561: for mappings of local notesfile names to remote notesfile names.
562: Each file in the directory is named after a system (e.g., pur-ee or uicsovax).
563: Each of these files contains lines which specify the mapping of local
564: notesfiles to the particular systems notesfiles.
565: Lines beginning with `#' in these files are comment lines and are ignored
566: in the matching process.
567: Data lines in the files look like:
568:
569: local_nf:remote_nf
570:
571: If there is no entry for a particular notesfile or
572: the file for that system is missing, the local name is used.
573:
574: Mapping is performed by the transmission program ``nfxmit''.
575: The ``nfrcv'' program does not consult this table.
576:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.