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