From f4d2a0f956f89e5b2a64778498c4f6d9489cb7f3 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 15 Oct 2005 16:04:26 +0000 Subject: [PATCH] STABLE14-pod-man-pages-20051015 FIXES 19268 add pod generation of man pages (cherry picked from commit 351a1e3d512dae952c5dcdaf4c818582a2450e85) --- Makefile.in | 10 +- configure.in | 7 + doc/man-pages/Makefile.in | 199 +++++++ doc/man-pages/generate-pod | 178 ++++++ doc/man-pages/pod/afs_intro.pod | 570 ++++++++++++++++++++ doc/man-pages/pod/afsd.pod | 597 +++++++++++++++++++++ doc/man-pages/pod/afsmonitor.pod | 432 +++++++++++++++ doc/man-pages/pod/backup.pod | 306 +++++++++++ doc/man-pages/pod/backup_adddump.pod | 202 +++++++ doc/man-pages/pod/backup_addhost.pod | 118 ++++ doc/man-pages/pod/backup_addvolentry.pod | 203 +++++++ doc/man-pages/pod/backup_addvolset.pod | 114 ++++ doc/man-pages/pod/backup_apropos.pod | 72 +++ doc/man-pages/pod/backup_dbverify.pod | 144 +++++ doc/man-pages/pod/backup_deldump.pod | 78 +++ doc/man-pages/pod/backup_deletedump.pod | 212 ++++++++ doc/man-pages/pod/backup_delhost.pod | 93 ++++ doc/man-pages/pod/backup_delvolentry.pod | 93 ++++ doc/man-pages/pod/backup_delvolset.pod | 83 +++ doc/man-pages/pod/backup_diskrestore.pod | 280 ++++++++++ doc/man-pages/pod/backup_dump.pod | 547 +++++++++++++++++++ doc/man-pages/pod/backup_dumpinfo.pod | 427 +++++++++++++++ doc/man-pages/pod/backup_help.pod | 95 ++++ doc/man-pages/pod/backup_interactive.pod | 121 +++++ doc/man-pages/pod/backup_jobs.pod | 229 ++++++++ doc/man-pages/pod/backup_kill.pod | 165 ++++++ doc/man-pages/pod/backup_labeltape.pod | 228 ++++++++ doc/man-pages/pod/backup_listdumps.pod | 135 +++++ doc/man-pages/pod/backup_listhosts.pod | 104 ++++ doc/man-pages/pod/backup_listvolsets.pod | 111 ++++ doc/man-pages/pod/backup_quit.pod | 77 +++ doc/man-pages/pod/backup_readlabel.pod | 242 +++++++++ doc/man-pages/pod/backup_restoredb.pod | 122 +++++ doc/man-pages/pod/backup_savedb.pod | 174 ++++++ doc/man-pages/pod/backup_scantape.pod | 359 +++++++++++++ doc/man-pages/pod/backup_setexp.pod | 175 ++++++ doc/man-pages/pod/backup_status.pod | 198 +++++++ doc/man-pages/pod/backup_volinfo.pod | 134 +++++ doc/man-pages/pod/backup_volrestore.pod | 336 ++++++++++++ doc/man-pages/pod/backup_volsetrestore.pod | 424 +++++++++++++++ doc/man-pages/pod/bos.pod | 299 +++++++++++ doc/man-pages/pod/bos_addhost.pod | 124 +++++ doc/man-pages/pod/bos_addkey.pod | 141 +++++ doc/man-pages/pod/bos_adduser.pod | 104 ++++ doc/man-pages/pod/bos_apropos.pod | 70 +++ doc/man-pages/pod/bos_create.pod | 410 ++++++++++++++ doc/man-pages/pod/bos_delete.pod | 101 ++++ doc/man-pages/pod/bos_exec.pod | 90 ++++ doc/man-pages/pod/bos_getdate.pod | 119 ++++ doc/man-pages/pod/bos_getlog.pod | 154 ++++++ doc/man-pages/pod/bos_getrestart.pod | 151 ++++++ doc/man-pages/pod/bos_help.pod | 95 ++++ doc/man-pages/pod/bos_install.pod | 139 +++++ doc/man-pages/pod/bos_listhosts.pod | 111 ++++ doc/man-pages/pod/bos_listkeys.pod | 142 +++++ doc/man-pages/pod/bos_listusers.pod | 98 ++++ doc/man-pages/pod/bos_prune.pod | 144 +++++ doc/man-pages/pod/bos_removehost.pod | 115 ++++ doc/man-pages/pod/bos_removekey.pod | 109 ++++ doc/man-pages/pod/bos_removeuser.pod | 100 ++++ doc/man-pages/pod/bos_restart.pod | 152 ++++++ doc/man-pages/pod/bos_salvage.pod | 354 ++++++++++++ doc/man-pages/pod/bos_setauth.pod | 114 ++++ doc/man-pages/pod/bos_setcellname.pod | 134 +++++ doc/man-pages/pod/bos_setrestart.pod | 190 +++++++ doc/man-pages/pod/bos_shutdown.pod | 133 +++++ doc/man-pages/pod/bos_start.pod | 103 ++++ doc/man-pages/pod/bos_startup.pod | 119 ++++ doc/man-pages/pod/bos_status.pod | 277 ++++++++++ doc/man-pages/pod/bos_stop.pod | 107 ++++ doc/man-pages/pod/bos_uninstall.pod | 120 +++++ doc/man-pages/pod/bosserver.pod | 162 ++++++ doc/man-pages/pod/buserver.pod | 159 ++++++ doc/man-pages/pod/butc.pod | 230 ++++++++ doc/man-pages/pod/dlog.pod | 230 ++++++++ doc/man-pages/pod/dpass.pod | 113 ++++ doc/man-pages/pod/fileserver.pod | 493 +++++++++++++++++ doc/man-pages/pod/fms.pod | 145 +++++ doc/man-pages/pod/fs.pod | 203 +++++++ doc/man-pages/pod/fs_apropos.pod | 71 +++ doc/man-pages/pod/fs_checkservers.pod | 234 ++++++++ doc/man-pages/pod/fs_checkvolumes.pod | 54 ++ doc/man-pages/pod/fs_cleanacl.pod | 102 ++++ doc/man-pages/pod/fs_copyacl.pod | 176 ++++++ doc/man-pages/pod/fs_diskfree.pod | 121 +++++ doc/man-pages/pod/fs_examine.pod | 126 +++++ doc/man-pages/pod/fs_exportafs.pod | 215 ++++++++ doc/man-pages/pod/fs_flush.pod | 85 +++ doc/man-pages/pod/fs_flushmount.pod | 76 +++ doc/man-pages/pod/fs_flushvolume.pod | 84 +++ doc/man-pages/pod/fs_getcacheparms.pod | 66 +++ doc/man-pages/pod/fs_getcellstatus.pod | 70 +++ doc/man-pages/pod/fs_getclientaddrs.pod | 109 ++++ doc/man-pages/pod/fs_getserverprefs.pod | 174 ++++++ doc/man-pages/pod/fs_help.pod | 95 ++++ doc/man-pages/pod/fs_listacl.pod | 196 +++++++ doc/man-pages/pod/fs_listcells.pod | 83 +++ doc/man-pages/pod/fs_listquota.pod | 111 ++++ doc/man-pages/pod/fs_lsmount.pod | 130 +++++ doc/man-pages/pod/fs_messages.pod | 98 ++++ doc/man-pages/pod/fs_mkmount.pod | 274 ++++++++++ doc/man-pages/pod/fs_newcell.pod | 112 ++++ doc/man-pages/pod/fs_quota.pod | 85 +++ doc/man-pages/pod/fs_rmmount.pod | 68 +++ doc/man-pages/pod/fs_setacl.pod | 293 ++++++++++ doc/man-pages/pod/fs_setcachesize.pod | 105 ++++ doc/man-pages/pod/fs_setcell.pod | 104 ++++ doc/man-pages/pod/fs_setclientaddrs.pod | 122 +++++ doc/man-pages/pod/fs_setquota.pod | 90 ++++ doc/man-pages/pod/fs_setserverprefs.pod | 320 +++++++++++ doc/man-pages/pod/fs_setvol.pod | 106 ++++ doc/man-pages/pod/fs_storebehind.pod | 231 ++++++++ doc/man-pages/pod/fs_sysname.pod | 94 ++++ doc/man-pages/pod/fs_whereis.pod | 74 +++ doc/man-pages/pod/fs_whichcell.pod | 68 +++ doc/man-pages/pod/fs_wscell.pod | 59 ++ doc/man-pages/pod/fstrace.pod | 88 +++ doc/man-pages/pod/fstrace_apropos.pod | 71 +++ doc/man-pages/pod/fstrace_clear.pod | 64 +++ doc/man-pages/pod/fstrace_dump.pod | 248 +++++++++ doc/man-pages/pod/fstrace_help.pod | 94 ++++ doc/man-pages/pod/fstrace_lslog.pod | 109 ++++ doc/man-pages/pod/fstrace_lsset.pod | 90 ++++ doc/man-pages/pod/fstrace_setlog.pod | 74 +++ doc/man-pages/pod/fstrace_setset.pod | 79 +++ doc/man-pages/pod/kadb_check.pod | 102 ++++ doc/man-pages/pod/kas.pod | 214 ++++++++ doc/man-pages/pod/kas_apropos.pod | 69 +++ doc/man-pages/pod/kas_create.pod | 125 +++++ doc/man-pages/pod/kas_delete.pod | 102 ++++ doc/man-pages/pod/kas_examine.pod | 308 +++++++++++ doc/man-pages/pod/kas_forgetticket.pod | 59 ++ doc/man-pages/pod/kas_help.pod | 99 ++++ doc/man-pages/pod/kas_interactive.pod | 157 ++++++ doc/man-pages/pod/kas_list.pod | 140 +++++ doc/man-pages/pod/kas_listtickets.pod | 111 ++++ doc/man-pages/pod/kas_noauthentication.pod | 64 +++ doc/man-pages/pod/kas_quit.pod | 55 ++ doc/man-pages/pod/kas_setfields.pod | 434 +++++++++++++++ doc/man-pages/pod/kas_setpassword.pod | 171 ++++++ doc/man-pages/pod/kas_statistics.pod | 148 +++++ doc/man-pages/pod/kas_stringtokey.pod | 96 ++++ doc/man-pages/pod/kas_unlock.pod | 104 ++++ doc/man-pages/pod/kaserver.pod | 175 ++++++ doc/man-pages/pod/kdb.pod | 143 +++++ doc/man-pages/pod/klog.pod | 349 ++++++++++++ doc/man-pages/pod/knfs.pod | 188 +++++++ doc/man-pages/pod/kpasswd.pod | 188 +++++++ doc/man-pages/pod/kpwvalid.pod | 85 +++ doc/man-pages/pod/pts.pod | 155 ++++++ doc/man-pages/pod/pts_adduser.pod | 126 +++++ doc/man-pages/pod/pts_apropos.pod | 67 +++ doc/man-pages/pod/pts_chown.pod | 103 ++++ doc/man-pages/pod/pts_creategroup.pod | 219 ++++++++ doc/man-pages/pod/pts_createuser.pod | 192 +++++++ doc/man-pages/pod/pts_delete.pod | 113 ++++ doc/man-pages/pod/pts_examine.pod | 288 ++++++++++ doc/man-pages/pod/pts_help.pod | 96 ++++ doc/man-pages/pod/pts_listentries.pod | 124 +++++ doc/man-pages/pod/pts_listmax.pod | 82 +++ doc/man-pages/pod/pts_listowned.pod | 140 +++++ doc/man-pages/pod/pts_membership.pod | 166 ++++++ doc/man-pages/pod/pts_removeuser.pod | 117 ++++ doc/man-pages/pod/pts_rename.pod | 113 ++++ doc/man-pages/pod/pts_setfields.pod | 264 +++++++++ doc/man-pages/pod/pts_setmax.pod | 92 ++++ 166 files changed, 26487 insertions(+), 2 deletions(-) create mode 100644 doc/man-pages/Makefile.in create mode 100755 doc/man-pages/generate-pod create mode 100644 doc/man-pages/pod/afs_intro.pod create mode 100644 doc/man-pages/pod/afsd.pod create mode 100644 doc/man-pages/pod/afsmonitor.pod create mode 100644 doc/man-pages/pod/backup.pod create mode 100644 doc/man-pages/pod/backup_adddump.pod create mode 100644 doc/man-pages/pod/backup_addhost.pod create mode 100644 doc/man-pages/pod/backup_addvolentry.pod create mode 100644 doc/man-pages/pod/backup_addvolset.pod create mode 100644 doc/man-pages/pod/backup_apropos.pod create mode 100644 doc/man-pages/pod/backup_dbverify.pod create mode 100644 doc/man-pages/pod/backup_deldump.pod create mode 100644 doc/man-pages/pod/backup_deletedump.pod create mode 100644 doc/man-pages/pod/backup_delhost.pod create mode 100644 doc/man-pages/pod/backup_delvolentry.pod create mode 100644 doc/man-pages/pod/backup_delvolset.pod create mode 100644 doc/man-pages/pod/backup_diskrestore.pod create mode 100644 doc/man-pages/pod/backup_dump.pod create mode 100644 doc/man-pages/pod/backup_dumpinfo.pod create mode 100644 doc/man-pages/pod/backup_help.pod create mode 100644 doc/man-pages/pod/backup_interactive.pod create mode 100644 doc/man-pages/pod/backup_jobs.pod create mode 100644 doc/man-pages/pod/backup_kill.pod create mode 100644 doc/man-pages/pod/backup_labeltape.pod create mode 100644 doc/man-pages/pod/backup_listdumps.pod create mode 100644 doc/man-pages/pod/backup_listhosts.pod create mode 100644 doc/man-pages/pod/backup_listvolsets.pod create mode 100644 doc/man-pages/pod/backup_quit.pod create mode 100644 doc/man-pages/pod/backup_readlabel.pod create mode 100644 doc/man-pages/pod/backup_restoredb.pod create mode 100644 doc/man-pages/pod/backup_savedb.pod create mode 100644 doc/man-pages/pod/backup_scantape.pod create mode 100644 doc/man-pages/pod/backup_setexp.pod create mode 100644 doc/man-pages/pod/backup_status.pod create mode 100644 doc/man-pages/pod/backup_volinfo.pod create mode 100644 doc/man-pages/pod/backup_volrestore.pod create mode 100644 doc/man-pages/pod/backup_volsetrestore.pod create mode 100644 doc/man-pages/pod/bos.pod create mode 100644 doc/man-pages/pod/bos_addhost.pod create mode 100644 doc/man-pages/pod/bos_addkey.pod create mode 100644 doc/man-pages/pod/bos_adduser.pod create mode 100644 doc/man-pages/pod/bos_apropos.pod create mode 100644 doc/man-pages/pod/bos_create.pod create mode 100644 doc/man-pages/pod/bos_delete.pod create mode 100644 doc/man-pages/pod/bos_exec.pod create mode 100644 doc/man-pages/pod/bos_getdate.pod create mode 100644 doc/man-pages/pod/bos_getlog.pod create mode 100644 doc/man-pages/pod/bos_getrestart.pod create mode 100644 doc/man-pages/pod/bos_help.pod create mode 100644 doc/man-pages/pod/bos_install.pod create mode 100644 doc/man-pages/pod/bos_listhosts.pod create mode 100644 doc/man-pages/pod/bos_listkeys.pod create mode 100644 doc/man-pages/pod/bos_listusers.pod create mode 100644 doc/man-pages/pod/bos_prune.pod create mode 100644 doc/man-pages/pod/bos_removehost.pod create mode 100644 doc/man-pages/pod/bos_removekey.pod create mode 100644 doc/man-pages/pod/bos_removeuser.pod create mode 100644 doc/man-pages/pod/bos_restart.pod create mode 100644 doc/man-pages/pod/bos_salvage.pod create mode 100644 doc/man-pages/pod/bos_setauth.pod create mode 100644 doc/man-pages/pod/bos_setcellname.pod create mode 100644 doc/man-pages/pod/bos_setrestart.pod create mode 100644 doc/man-pages/pod/bos_shutdown.pod create mode 100644 doc/man-pages/pod/bos_start.pod create mode 100644 doc/man-pages/pod/bos_startup.pod create mode 100644 doc/man-pages/pod/bos_status.pod create mode 100644 doc/man-pages/pod/bos_stop.pod create mode 100644 doc/man-pages/pod/bos_uninstall.pod create mode 100644 doc/man-pages/pod/bosserver.pod create mode 100644 doc/man-pages/pod/buserver.pod create mode 100644 doc/man-pages/pod/butc.pod create mode 100644 doc/man-pages/pod/dlog.pod create mode 100644 doc/man-pages/pod/dpass.pod create mode 100644 doc/man-pages/pod/fileserver.pod create mode 100644 doc/man-pages/pod/fms.pod create mode 100644 doc/man-pages/pod/fs.pod create mode 100644 doc/man-pages/pod/fs_apropos.pod create mode 100644 doc/man-pages/pod/fs_checkservers.pod create mode 100644 doc/man-pages/pod/fs_checkvolumes.pod create mode 100644 doc/man-pages/pod/fs_cleanacl.pod create mode 100644 doc/man-pages/pod/fs_copyacl.pod create mode 100644 doc/man-pages/pod/fs_diskfree.pod create mode 100644 doc/man-pages/pod/fs_examine.pod create mode 100644 doc/man-pages/pod/fs_exportafs.pod create mode 100644 doc/man-pages/pod/fs_flush.pod create mode 100644 doc/man-pages/pod/fs_flushmount.pod create mode 100644 doc/man-pages/pod/fs_flushvolume.pod create mode 100644 doc/man-pages/pod/fs_getcacheparms.pod create mode 100644 doc/man-pages/pod/fs_getcellstatus.pod create mode 100644 doc/man-pages/pod/fs_getclientaddrs.pod create mode 100644 doc/man-pages/pod/fs_getserverprefs.pod create mode 100644 doc/man-pages/pod/fs_help.pod create mode 100644 doc/man-pages/pod/fs_listacl.pod create mode 100644 doc/man-pages/pod/fs_listcells.pod create mode 100644 doc/man-pages/pod/fs_listquota.pod create mode 100644 doc/man-pages/pod/fs_lsmount.pod create mode 100644 doc/man-pages/pod/fs_messages.pod create mode 100644 doc/man-pages/pod/fs_mkmount.pod create mode 100644 doc/man-pages/pod/fs_newcell.pod create mode 100644 doc/man-pages/pod/fs_quota.pod create mode 100644 doc/man-pages/pod/fs_rmmount.pod create mode 100644 doc/man-pages/pod/fs_setacl.pod create mode 100644 doc/man-pages/pod/fs_setcachesize.pod create mode 100644 doc/man-pages/pod/fs_setcell.pod create mode 100644 doc/man-pages/pod/fs_setclientaddrs.pod create mode 100644 doc/man-pages/pod/fs_setquota.pod create mode 100644 doc/man-pages/pod/fs_setserverprefs.pod create mode 100644 doc/man-pages/pod/fs_setvol.pod create mode 100644 doc/man-pages/pod/fs_storebehind.pod create mode 100644 doc/man-pages/pod/fs_sysname.pod create mode 100644 doc/man-pages/pod/fs_whereis.pod create mode 100644 doc/man-pages/pod/fs_whichcell.pod create mode 100644 doc/man-pages/pod/fs_wscell.pod create mode 100644 doc/man-pages/pod/fstrace.pod create mode 100644 doc/man-pages/pod/fstrace_apropos.pod create mode 100644 doc/man-pages/pod/fstrace_clear.pod create mode 100644 doc/man-pages/pod/fstrace_dump.pod create mode 100644 doc/man-pages/pod/fstrace_help.pod create mode 100644 doc/man-pages/pod/fstrace_lslog.pod create mode 100644 doc/man-pages/pod/fstrace_lsset.pod create mode 100644 doc/man-pages/pod/fstrace_setlog.pod create mode 100644 doc/man-pages/pod/fstrace_setset.pod create mode 100644 doc/man-pages/pod/kadb_check.pod create mode 100644 doc/man-pages/pod/kas.pod create mode 100644 doc/man-pages/pod/kas_apropos.pod create mode 100644 doc/man-pages/pod/kas_create.pod create mode 100644 doc/man-pages/pod/kas_delete.pod create mode 100644 doc/man-pages/pod/kas_examine.pod create mode 100644 doc/man-pages/pod/kas_forgetticket.pod create mode 100644 doc/man-pages/pod/kas_help.pod create mode 100644 doc/man-pages/pod/kas_interactive.pod create mode 100644 doc/man-pages/pod/kas_list.pod create mode 100644 doc/man-pages/pod/kas_listtickets.pod create mode 100644 doc/man-pages/pod/kas_noauthentication.pod create mode 100644 doc/man-pages/pod/kas_quit.pod create mode 100644 doc/man-pages/pod/kas_setfields.pod create mode 100644 doc/man-pages/pod/kas_setpassword.pod create mode 100644 doc/man-pages/pod/kas_statistics.pod create mode 100644 doc/man-pages/pod/kas_stringtokey.pod create mode 100644 doc/man-pages/pod/kas_unlock.pod create mode 100644 doc/man-pages/pod/kaserver.pod create mode 100644 doc/man-pages/pod/kdb.pod create mode 100644 doc/man-pages/pod/klog.pod create mode 100644 doc/man-pages/pod/knfs.pod create mode 100644 doc/man-pages/pod/kpasswd.pod create mode 100644 doc/man-pages/pod/kpwvalid.pod create mode 100644 doc/man-pages/pod/pts.pod create mode 100644 doc/man-pages/pod/pts_adduser.pod create mode 100644 doc/man-pages/pod/pts_apropos.pod create mode 100644 doc/man-pages/pod/pts_chown.pod create mode 100644 doc/man-pages/pod/pts_creategroup.pod create mode 100644 doc/man-pages/pod/pts_createuser.pod create mode 100644 doc/man-pages/pod/pts_delete.pod create mode 100644 doc/man-pages/pod/pts_examine.pod create mode 100644 doc/man-pages/pod/pts_help.pod create mode 100644 doc/man-pages/pod/pts_listentries.pod create mode 100644 doc/man-pages/pod/pts_listmax.pod create mode 100644 doc/man-pages/pod/pts_listowned.pod create mode 100644 doc/man-pages/pod/pts_membership.pod create mode 100644 doc/man-pages/pod/pts_removeuser.pod create mode 100644 doc/man-pages/pod/pts_rename.pod create mode 100644 doc/man-pages/pod/pts_setfields.pod create mode 100644 doc/man-pages/pod/pts_setmax.pod diff --git a/Makefile.in b/Makefile.in index 47a9d55456..0825a85b9a 100644 --- a/Makefile.in +++ b/Makefile.in @@ -340,6 +340,11 @@ login: cmd comerr kauth rxkad pam sia tsm41 sgistuff aklog echo Skipping login for ${SYS_NAME} ; \ fi +man-pages: + if test -d "doc/man-pages" ; then \ + cd doc/man-pages ${COMPILE_PART2} ; \ + fi + # # _depinstall targets - only build and install headers/sources that are needed by libafs/libuafs # @@ -566,13 +571,13 @@ jafsadm: libjafsadm finale: project cmd comerr afsd butc tbutc @ENABLE_KERNEL_MODULE@ libuafs audit kauth log package \ ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \ venus update xstat afsmonitor dauth rxdebug libafsrpc \ - libafsauthent shlibafsrpc shlibafsauthent libadmin login + libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages ${COMPILE_PART1} finale ${COMPILE_PART2} finale_nolibafs: project cmd comerr afsd butc tbutc libuafs audit kauth log package \ ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \ venus update xstat afsmonitor dauth rxdebug libafsrpc \ - libafsauthent shlibafsrpc shlibafsauthent libadmin login + libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages ${COMPILE_PART1} finale ${COMPILE_PART2} # Use washtool to ensure MakefileProto is current and obj/libafs exists. @@ -807,6 +812,7 @@ distclean: clean src/wsadmin.src/Makefile \ src/xstat/Makefile \ src/helper-splint.sh + if test -d doc/man-pages ; then rm -f doc/man-pages/Makefile ; fi pristine: distclean /bin/rm -f src/config/afsconfig.h.in configure configure-libafs aclocal.m4 diff --git a/configure.in b/configure.in index e85e7555fb..29f10ba07b 100644 --- a/configure.in +++ b/configure.in @@ -5,8 +5,15 @@ AC_CONFIG_HEADER(src/config/afsconfig.h) AC_PROG_CC OPENAFS_CONFIGURE_COMMON +if test -d 'doc/man-pages' ; then + MAN_MAKEFILE=doc/man-pages/Makefile +else + MAN_MAKEFILE= +fi + AC_OUTPUT( \ Makefile \ +${MAN_MAKEFILE} \ src/afs/Makefile \ src/afsd/Makefile \ src/afsmonitor/Makefile \ diff --git a/doc/man-pages/Makefile.in b/doc/man-pages/Makefile.in new file mode 100644 index 0000000000..bcad3eade4 --- /dev/null +++ b/doc/man-pages/Makefile.in @@ -0,0 +1,199 @@ +# Makefile for AFS man pages + +srcdir=@srcdir@ +include @TOP_OBJDIR@/src/config/Makefile.config + +MAN1 = \ + afs_intro.1 \ + fs.1 \ + fs_apropos.1 \ + fs_checkservers.1 \ + fs_checkvolumes.1 \ + fs_cleanacl.1 \ + fs_copyacl.1 \ + fs_diskfree.1 \ + fs_examine.1 \ + fs_exportafs.1 \ + fs_flush.1 \ + fs_flushmount.1 \ + fs_flushvolume.1 \ + fs_getcacheparms.1 \ + fs_getcellstatus.1 \ + fs_getclientaddrs.1 \ + fs_getserverprefs.1 \ + fs_help.1 \ + fs_listacl.1 \ + fs_listcells.1 \ + fs_listquota.1 \ + fs_lsmount.1 \ + fs_messages.1 \ + fs_mkmount.1 \ + fs_newcell.1 \ + fs_quota.1 \ + fs_rmmount.1 \ + fs_setacl.1 \ + fs_setcachesize.1 \ + fs_setcell.1 \ + fs_setclientaddrs.1 \ + fs_setquota.1 \ + fs_setserverprefs.1 \ + fs_setvol.1 \ + fs_storebehind.1 \ + fs_sysname.1 \ + fs_whereis.1 \ + fs_whichcell.1 \ + fs_wscell.1 \ + klog.1 \ + kpasswd.1 \ + kpwvalid.1 \ + pts.1 \ + pts_adduser.1 \ + pts_apropos.1 \ + pts_chown.1 \ + pts_creategroup.1 \ + pts_createuser.1 \ + pts_delete.1 \ + pts_examine.1 \ + pts_help.1 \ + pts_listentries.1 \ + pts_listmax.1 \ + pts_listowned.1 \ + pts_membership.1 \ + pts_removeuser.1 \ + pts_rename.1 \ + pts_setfields.1 \ + pts_setmax.1 + +MAN8 = \ + afsd.8 \ + afsmonitor.8 \ + backup.8 \ + backup_adddump.8 \ + backup_addhost.8 \ + backup_addvolentry.8 \ + backup_addvolset.8 \ + backup_apropos.8 \ + backup_dbverify.8 \ + backup_deldump.8 \ + backup_deletedump.8 \ + backup_delhost.8 \ + backup_delvolentry.8 \ + backup_delvolset.8 \ + backup_diskrestore.8 \ + backup_dump.8 \ + backup_dumpinfo.8 \ + backup_help.8 \ + backup_interactive.8 \ + backup_jobs.8 \ + backup_kill.8 \ + backup_labeltape.8 \ + backup_listdumps.8 \ + backup_listhosts.8 \ + backup_listvolsets.8 \ + backup_quit.8 \ + backup_readlabel.8 \ + backup_restoredb.8 \ + backup_savedb.8 \ + backup_scantape.8 \ + backup_setexp.8 \ + backup_status.8 \ + backup_volinfo.8 \ + backup_volrestore.8 \ + backup_volsetrestore.8 \ + bos.8 \ + bos_addhost.8 \ + bos_addkey.8 \ + bos_adduser.8 \ + bos_apropos.8 \ + bos_create.8 \ + bos_delete.8 \ + bos_exec.8 \ + bos_getdate.8 \ + bos_getlog.8 \ + bos_getrestart.8 \ + bos_help.8 \ + bos_install.8 \ + bos_listhosts.8 \ + bos_listkeys.8 \ + bos_listusers.8 \ + bos_prune.8 \ + bos_removehost.8 \ + bos_removekey.8 \ + bos_removeuser.8 \ + bos_restart.8 \ + bos_salvage.8 \ + bos_setauth.8 \ + bos_setcellname.8 \ + bos_setrestart.8 \ + bos_shutdown.8 \ + bos_start.8 \ + bos_startup.8 \ + bos_status.8 \ + bos_stop.8 \ + bos_uninstall.8 \ + bosserver.8 \ + buserver.8 \ + butc.8 \ + dlog.8 \ + dpass.8 \ + fileserver.8 \ + fms.8 \ + fstrace.8 \ + fstrace_apropos.8 \ + fstrace_clear.8 \ + fstrace_dump.8 \ + fstrace_help.8 \ + fstrace_lslog.8 \ + fstrace_lsset.8 \ + fstrace_setlog.8 \ + fstrace_setset.8 \ + kadb_check.8 \ + kas.8 \ + kas_apropos.8 \ + kas_create.8 \ + kas_delete.8 \ + kas_examine.8 \ + kas_forgetticket.8 \ + kas_help.8 \ + kas_interactive.8 \ + kas_list.8 \ + kas_listtickets.8 \ + kas_noauthentication.8 \ + kas_quit.8 \ + kas_setfields.8 \ + kas_setpassword.8 \ + kas_statistics.8 \ + kas_stringtokey.8 \ + kas_unlock.8 \ + kaserver.8 \ + kdb.8 \ + knfs.8 + +all: $(MAN1) $(MAN8) + +%.1: $(srcdir)/pod/%.pod + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 $< $@ + +%.8: $(srcdir)/pod/%.pod + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 $< $@ + +clean: + rm -f *.1 *.8 + +dest: $(MAN1) $(MAN8) + mkdir -p $(DEST)/man/man1 $(DEST)/man/man8 + set -e; for M in $(MAN1) ; do \ + $(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \ + done + set -e; for M in $(MAN8) ; do \ + $(INSTALL) -c -m 0644 $$M $(DEST)/man/man8/$$M ; \ + done + +install: $(MAN1) $(MAN8) + mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man8 + set -e; for M in $(MAN1) ; do \ + $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \ + done + set -e; for M in $(MAN8) ; do \ + $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \ + done diff --git a/doc/man-pages/generate-pod b/doc/man-pages/generate-pod new file mode 100755 index 0000000000..706d14dbc2 --- /dev/null +++ b/doc/man-pages/generate-pod @@ -0,0 +1,178 @@ +#!/usr/bin/perl -w +# +# Parser for files obtained via +# lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt + +use strict; +my $DEBUG = 0; +my $RAW = 0; + +my %hash; +my %options; + +###################################################################### +## Input Section: +###################################################################### + +my $del = $/; +undef $/; +my $text = ; +$/ = $del; + +my $sections = 'Purpose|Synopsis|Description|Cautions|Options|Output|Examples|Privilege\ Required|Related\ Information|References'; + +$text =~ s/^.*\[7\]\s*(.+?)\n//xs; + +$hash{Command} = $1; +my $Cmd_fam = "backup|bos|fs|kas|pts|uss|vos"; +$Cmd_fam .= '|' . (split(" ", $hash{Command}))[0]; + +while ($text !~ /^\s+$/xs) { + $text =~ s/($sections)(.*?)(\n\s*(?:$sections)\n\s*|$)/$3/xs; + $hash{$1} = $2; +} + +$hash{'Related Information'} =~ s/\s*(.+?)\s*___________.*$/$1/xs; + + + +if (! $RAW) { + ###################################################################### + ## Clean-up Section: + ###################################################################### + + # make C out of pts adduser: + $hash{Description} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Description}); + $hash{Options} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Options}); + + # strip leading and trailing whitespace: + my $pattern = '^\s*(.*?)\s*$'; + foreach (keys(%hash)) { + $hash{$_} =~ s/$pattern/$1/sxg; + $hash{$_} =~ s/\n\ +/\n/sxg; + $hash{$_} =~ s/((?:$Cmd_fam)\s?\w*)(\s)reference(\s)page/L<$1(1)>$2reference$3page/g; + $hash{$_} =~ s/the(\s)(\w+(?:\s\w+)?)(\s)reference(\s)page/the$1L<$2(1)>$3reference$4page/g; + $hash{$_} =~ s/(\(?\b(?:$Cmd_fam)\)?\s?\w*)(\s)command/C<$1>$2command/g; + $hash{$_} =~ s/the(\s)(\w+)(\s)command/the$1C<$2>$3command/g; + $hash{$_} =~ s/\n\*\ /\n\n=item \*\n\n/g; + $hash{$_} =~ s/\n\+\ /\n\n=item \*\n\n/g; + $hash{$_} =~ s"(\s)((?:/\w+)+)"$1B<$2>"g if($_ ne "Synopsis"); + $hash{$_} =~ s/(superuser\s)root/$1B/g; + $hash{$_} =~ s/(unprivileged\s(?:identity|user)\s)anonymous/$1B/g; + $hash{$_} =~ s/system\:administrators/B/g; + $hash{$_} =~ s/(\s)(\w)(\s)\((\w+)\)(\s)/$1B<$2>$3(B<$4>)$5/g; + } + + ###################################################################### + ## POD-ify Section: + ###################################################################### + + # Make B<-group> out of -group: + $hash{Synopsis} =~ s/(\s|^|\[)(-\w+)\b/$1B<$2>/g if ($hash{Synopsis}); + $hash{Description} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Description}); + $hash{Options} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Options}); + $hash{Output} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Output}); + $hash{Cautions} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Cautions}); + $hash{'Privilege Required'} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{'Privilege Required'}); + + $hash{Description} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Description}); + $hash{Options} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Options}); + $hash{Output} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Output}); + $hash{'Privilege Required'} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{'Privilege Required'}); + $hash{Cautions} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Cautions}); + + $hash{Synopsis} =~ s/<([^>]*?)>\^\+/I<$1> [I<$1> ...]/g if ($hash{Synopsis}); + $hash{Synopsis} =~ s/( |\n)<(.*?)>/$1I<$2>/g if ($hash{Synopsis}); + $text = $hash{Synopsis}; + while ($text && $text =~ /B<-\w+> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?/s) { + $text =~ s/B<(-\w+)> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?//s; + if ($2) { + $options{$1} = ' '.$2; + } else { + $options{$1} = ""; + } + } + + $hash{Options} =~ s/(?:\n|^)B<([^>]*?)>\ \n/\n=item B<$1>$options{$1}\n\n/sxg if ($hash{Options}); + + $hash{Examples} =~ s/\n\s*%(.*?)(?:\n|$)/\n\nB<\ \ \ $1>\n/sxg if ($hash{Examples}); + + $hash{'Related Information'} =~ s/\[\d+\](.*?)\s*\n/L<$1(1)>,\n/msxg if ($hash{'Related Information'}); + $hash{'Related Information'} =~ s/\[\d+\](.*)\s*/L<$1(1)>/msxg if ($hash{'Related Information'}); + $hash{'Related Information'} =~ s/(\w+)\s+(\w+)/$1_$2/msxg if ($hash{'Related Information'}); + + foreach (keys(%hash)) { + $hash{$_} =~ s/((?:\n\n=item\ \*\n(?:\n.+$)+)+)/\n\n=over$1\n\n=back/mxg; + } + + +}; + + +###################################################################### +## Output Section: +###################################################################### + +my $file; +($file = $hash{Command} . ".pod") =~ s/\s/_/g; + +my $FH; +if ($DEBUG) { + $FH = *STDOUT +} else { + open(FILE, "> $file") || die("Could not open $file\n"); + $FH = *FILE; +} + +print $FH "=head1 NAME\n\n"; +print $FH "$hash{Command} - $hash{Purpose}\n\n"; + +if (exists $hash{Synopsis}) { + print $FH "=head1 SYNOPSIS\n\n"; + print $FH "$hash{Synopsis}\n\n"; +} + +print $FH "=head1 DESCRIPTION\n\n"; +print $FH "$hash{Description}\n\n"; + +if (exists $hash{Options}) { + print $FH "=head1 OPTIONS\n\n"; + print $FH "=over 4\n"; + print $FH "$hash{Options}\n\n"; + print $FH "=back\n\n"; +} + +if (exists $hash{Output}) { + print $FH "=head1 OUTPUT\n\n"; + print $FH "$hash{Output}\n\n"; +} + +if (exists $hash{Examples}) { + print $FH "=head1 EXAMPLES\n\n"; + print $FH "$hash{Examples}\n\n"; +} + +if (exists $hash{'Privilege Required'}) { + print $FH "=head1 PRIVILEGE REQUIRED\n\n"; + print $FH "$hash{'Privilege Required'}\n\n"; +} + +if (exists $hash{Cautions}) { + print $FH "=head1 CAVEATS\n\n"; + print $FH "$hash{Cautions}\n\n"; +} + +print $FH "=head1 COPYRIGHT\n\n"; +print $FH "IBM Corporation 2000. All Rights Reserved.\n\n"; +print $FH "Converted from html to pod by Alf Wachsmann , 2003,\n"; +print $FH "and Elizabeth Cassell , 2004,\n"; +print $FH "Stanford Linear Accelerator Center, a department of Stanford University.\n\n"; + +if (exists $hash{'Related Information'}) { + print $FH "=head1 SEE ALSO\n\n"; + print $FH "$hash{'Related Information'}\n\n"; + print $FH "=cut\n"; +} + +close(FILE) unless $DEBUG; + diff --git a/doc/man-pages/pod/afs_intro.pod b/doc/man-pages/pod/afs_intro.pod new file mode 100644 index 0000000000..43d43c97de --- /dev/null +++ b/doc/man-pages/pod/afs_intro.pod @@ -0,0 +1,570 @@ +=head1 NAME + +afs_intro - Introduction to AFS commands + +=head1 DESCRIPTION + +AFS provides many commands that enable users and system administrators +to use and customize its features. Many of the commands belong to the +following categories, called command suites. + +=over + +=item B + +Interface for configuring and operating the AFS Backup System + +=item B + +Interface to the Basic Overseer (BOS) Server for administering +server processes and configuration files + +=item B + +Interface for administering access control lists (ACLs), the +Cache Manager, and other miscellaneous file system functions + +=item B + +Interface for tracing Cache Manager operations when debugging +problems + +=item B + +Interface to the Authentication Server for administering +security and authentication information + +=item B + +Interface to the Protection Server for administering AFS ID and +group membership information + +=item B + +Interface for automated administration of user accounts + +=item B + +Interface to the Volume Server and Volume Location (VL) Server +for administering volumes + +=back + +In addition, there are several commands that do not belong to suites. + +=head2 AFS Command Syntax + +AFS commands that belong to suites have the following structure: + +B B B<-switch> I [I ...] [B<-flag>] + +=head2 Command Names + +Together, the B and B make up the command +name. + +The B specifies the group of related commands to which the +command belongs, and indicates which command interpreter and server +process perform the command. AFS has several command suites, including +B, B, B, B, B, B, B and B. Some of these suites +have an interactive mode in which the issuer omits the B +portion of the command name. + +The B tells the command interpreter and server process +which action to perform. Most command suites include several operation +codes. The IBM AFS Administration Reference describes each operation +code in detail, and the IBM AFS Administration Guide describes how to +use them in the context of performing administrative tasks. + +Several AFS commands do not belong to a suite and so their names do +not have a B portion. Their structure is otherwise similar +to the commands in the suites. + +=head1 OPTIONS + +The term option refers to both arguments and flags, which are +described in the following sections. + +=head2 Arguments + +One or more arguments can follow the command name. Arguments specify +the entities on which to act while performing the command (for +example, which server machine, server process, or file). To minimize +the potential for error, provide a command's arguments in the order +prescribed in its syntax definition. + +Each argument has two parts, which appear in the indicated order: + +=over + +=item * + +The switch specifies the argument's type and is preceded by a +hyphen ( B<-> ). For instance, the switch B<-server> usually indicates +that the argument names a server machine. Switches can often be +omitted, subject to the rules outlined in L. + +=item * + +The I names a particular entity of the type specified by the +preceding switch. For example, the proper value for a B<-server> +switch is a server machine name like B. Unlike switches +(which have a required form), values vary depending on what the +issuer wants to accomplish. Values appear surrounded by angle +brackets (B E>) in command descriptions and the online help to show +that they are user-supplied variable information. + +=back + +Some arguments accept multiple values, as indicated by trailing ellipsis +( B<...> ) in the command descriptions and online help. How many of a +command's arguments take multiple values, and their ordering with +respect to other arguments, determine when it is acceptable to omit +switches. See L. + +Some commands have optional as well as required arguments; the command +descriptions and online help show optional arguments in square +brackets ([ ]). + +=head2 Flags + +Some commands have one or more flags, which specify the manner in +which the command interpreter and server process perform the command, +or what kind of output it produces. Flags are preceded by hyphens like +switches, but they take no values. Although the command descriptions +and online help generally list a command's flags after its arguments, +there is no prescribed order for flags. They can appear anywhere on +the command line following the operation code, except in between the +parts of an argument. Flags are always optional. + +=head2 An Example Command + +The following example illustrates the different parts of a command +that belongs to an AFS command suite. + + bos getdate -server fs1.abc.com -file ptserver kaserver + +where + +=over + +=item * + +B is the command suite. The BOS Server executes most of the +commands in this suite. + +=item * + +B is the operation code. It tells the BOS Server on the +specified server machine (in this case B) to report the +modification dates of binary files in the local B +directory. + +=item * + +B<-server> B is one argument, with B<-server> as the switch +and B as the value. This argument specifies the server +machine on which BOS Server is to collect and report binary dates. + +=item * + +B<-file> B B is an argument that takes multiple values. +The switch is B<-file> and the values are B and B. This +argument tells the BOS Server to report the modification dates on +the files B and B. + +=back + +=head2 Rules for Entering AFS Commands + +Enter each AFS command on a single line (press BReturnE> only at the +end of the command). Some commands in this document appear broken +across multiple lines, but that is for legibility only. + +Use a space to separate each element on a command line from its +neighbors. Spaces rather than commas also separate multiple values of +an argument. + +In many cases, the issuer of a command can reduce the amount of typing +necessary by using one or both of the following methods: + +=over + +=item * + +Omitting switches + +=item * + +Using accepted abbreviations for operation codes, switches (if +they are included at all), and some types of values + +=back + +The following sections explain the conditions for omitting or +shortening parts of the command line. It is always acceptable to type +a command in full, with all of its switches and no abbreviations. + +=head3 Conditions for Omitting Switches + +It is always acceptable to type the switch part of an argument, but in +many cases it is not necessary. Specifically, switches can be omitted +if the following conditions are met. + +=over + +=item * + +All of the command's required arguments appear in the order +prescribed by the syntax statement + +=item * + +No switch is provided for any argument + +=item * + +There is only one value for each argument (but note the important +exception discussed in the following paragraph) + +=back + +Omitting switches is possible only because there is a prescribed order +for each command's arguments. When the issuer does not include +switches, the command interpreter relies instead on the order of +arguments; it assumes that the first element after the operation code +is the command's first argument, the next element is the command's +second argument, and so on. The important exception is when a +command's final required argument accepts multiple values. In this +case, the command interpreter assumes that the issuer has correctly +provided one value for each argument up through the final one, so any +additional values at the end belong to the final argument. + +The following list describes the rules for omitting switches from the +opposite perspective: an argument's switch must be provided when any +of the following conditions apply. + +=over + +=item * + +The command's arguments do not appear in the prescribed order + +=item * + +An optional argument is omitted but a subsequent optional argument +is provided + +=item * + +A switch is provided for a preceding argument + +=item * + +More than one value is supplied for a preceding argument (which +must take multiple values, of course); without a switch on the +current argument, the command interpreter assumes that the current +argument is another value for the preceding argument + +=back + +=head3 An Example of Omitting Switches + +Consider again the example command from L. + + bos getdate -server fs1.abc.com -file ptserver kaserver + +This command has two required arguments: the server machine name +(identified by the B<-server> switch) and binary file name (identified by +the B<-file> switch). The second argument accepts multiple values. By +complying with all three conditions, the issuer can omit the switches: + + bos getdate fs1.abc.com ptserver kaserver + +Because there are no switches, the C command interpreter relies on +the order of arguments. It assumes that the first element following +the operation code, B, is the server machine name, and that +the next argument, B, is a binary file name. Then, because the +command's second (and last) argument accepts multiple values, the +command interpreter correctly interprets B as an additional +value for it. + +On the other hand, the following is not acceptable because it violates +the first two conditions in L: even +though there is only one value per argument, the arguments do not +appear in the prescribed order, and a switch is provided for one +argument but not the other. + + bos getdate ptserver -server fs1.abc.com + +=head2 Rules for Using Abbreviations and Aliases + +This section explains how to abbreviate operation codes, option names, +server machine names, partition names, and cell names. It is not +possible to abbreviate other types of values. + +=head3 Abbreviating Operation Codes + +It is acceptable to abbreviate an operation code to the shortest form +that still distinguishes it from the other operation codes in its suite. + +For example, it is acceptable to shorten bos install to bos i because +there are no other operation codes in the bos command suite that begin +with the letter i. In contrast, there are several bos operation codes +that start with the letter s, so the abbreviations must be longer to +remain unambiguous: + +C for C + +C for C + +C for C + +C for C + +C for C + +C for C + +C for C + +C for C + +C for C + +In addition to abbreviations, some operation codes have an I, a +short form that is not derived by abbreviating the operation code to +its shortest unambiguous form. For example, the alias for the C command is C, whereas the shortest unambiguous abbreviation +is C. + +There are two usual reasons an operation code has an alias: + +=over + +=item * + +Because the command is frequently issued, it is convenient to have +a form shorter than the one derived by abbreviating. The C +command is an example. + +=item * + +Because the command's name has changed, but users of previous +versions of AFS know the former name. For example, C +has the alias C, its former name. It is acceptable to +abbreviate aliases to their shortest unambiguous form (for +example, C to C). + +=back + +Even if an operation code has an alias, it is still acceptable to use +the shortest unambiguous form. Thus, the C command has three +acceptable forms: C (the full form), C (the shortest +abbreviation), and C (the alias). + +=head3 Abbreviating Switches and Flags + +It is acceptable to shorten a switch or flag to the shortest form that +distinguishes it from the other switches and flags for its operation +code. It is often possible to omit switches entirely, subject to the +conditions listed in L. + +=head3 Abbreviating Server Machine Names + +AFS server machines must have fully-qualified Internet-style host +names (for example, B), but it is not always necessary to +type the full name on the command line. AFS commands accept +unambiguous shortened forms, but depend on the cell's name service +(such as the Domain Name Service) or a local host table to resolve a +shortened name to the fully-qualified equivalent when the command is +issued. + +Most commands also accept the dotted decimal form of the machine's IP +address as an identifier. + +=head3 Abbreviating Partition Names + +Partitions that house AFS volumes must have names of the form +BI or BI, where the variable final portion is one or +two lowercase letters. By convention, the first server partition +created on a file server machine is called B, the second +B, and so on. The IBM AFS Quick Beginnings explains how to +configure and name a file server machine's partitions in +preparation for storing AFS volumes on them. + +When issuing AFS commands, you can abbreviate a partition name using +any of the following forms: + + /vicepa = vicepa = a = 0 + /vicepb = vicepb = b = 1 + +After B (for which the index is 25) comes + + /vicepaa = vicepaa = aa = 26 + /vicepab = vicepab = ab = 27 + +and so on through + + /vicepiv = vicepiv = iv = 255 + +=head3 Abbreviating Cell Names + +A cell's full name usually matches its Internet domain name (such +as B for the State University or B for ABC Corporation). +Some AFS commands accept unambiguous shortened forms, usually with +respect to the local B file but sometimes +depending on the ability of the local name service to resolve the +corresponding domain name. + +=head2 Displaying Online Help for AFS Commands + +To display online help for AFS commands that belong to suites, use the +C and C operation codes. A B<-help> flag is also available on +almost every AFS command. + +The online help entry for a command consists of two or three lines: + +=over + +=item * + +The first line names the command and briefly describes what it +does + +=item * + +If the command has aliases, they appear on the next line + +=item * + +The final line, which begins with the string C, lists the +command's options in the prescribed order; online help entries use +the same typographical symbols (brackets and so on) as this +documentation. + +=back + +If no operation code is specified, the B operation code displays +the first line (short description) for every operation code in the +suite: + + command_suite help + +If the issuer specifies one or more operation codes, the help +operation code displays each command's complete online entry (short +description, alias if any, and syntax): + + command_suite help operation_code [operation_code ...] + +The B<-help> flag displays a command's syntax but not the short +description or alias: + + command_name -help + +The B operation code displays the short description of any +command in a suite whose operation code or short description includes +the specified keyword: + + command_suite apropos "help string" + +The following example command displays the complete online help entry +for the C command: + + fs help setacl + fs setacl: set access control list + aliases: sa + Usage: fs setacl B<-dir> + B<-acl> + + [-clear] [-negative] [-id] [-if] [-help] + +To see only the syntax statement, use the B<-help> flag: + + fs setacl B<-help> + Usage: fs setacl B<-dir> + B<-acl> + + [-clear] [-negative] [-id] [-if] [-help] + +In the following example, a user wants to display the quota for her +home volume. She knows that the relevant command belongs to the C +suite, but cannot remember the operation code. She uses C as the +keyword: + + fs apropos quota + listquota: list volume quota + quota: show volume quota usage + setquota: set volume quota + +The following illustrates the error message that results if no command +name or short description contains the keyword: + + fs apropos "list quota" + Sorry, no commands found + +=head1 PRIVILEGE REQUIRED + +Many AFS commands require one or more types of administrative +privilege. See the reference page for each command. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/afsd.pod b/doc/man-pages/pod/afsd.pod new file mode 100644 index 0000000000..01c1efe785 --- /dev/null +++ b/doc/man-pages/pod/afsd.pod @@ -0,0 +1,597 @@ +=head1 NAME + +afsd - Initializes the Cache Manager and starts related daemons. + +=head1 SYNOPSIS + +afsd [B<-blocks> I<1024 byte blocks in cache>] +[B<-files> I] +[B<-rootvol> I] +[B<-stat> I] +[B<-memcache>] [B<-cachedir> I] +[B<-mountdir> I] +[B<-daemons> I] +[B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [B<-debug>] +[B<-chunksize> I] +[B<-dcache> I] +[B<-volumes> I] +[B<-biods> I] +[B<-prealloc> I] +[B<-confdir> I] +[B<-logfile> I] +[B<-waitclose>] [B<-shutdown>] [B<-enable_peer_stats>] +[B<-enable_process_stats>] [B<-help>] + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + +=head1 DESCRIPTION + +The C command initializes the Cache Manager on an AFS client +machine by transferring AFS-related configuration information into +kernel memory and starting several daemons. More specifically, the +C command performs the following actions: + +=over + +=item * + +Sets a field in kernel memory that defines the machine's cell +membership. Some Cache Manager-internal operations and system +calls consult this field to learn which cell to execute in. (The +AFS command interpreters refer to the B file +instead.) This information is transferred into the kernel from the +B file and cannot be changed until the C +program runs again. + +=item * + +Places in kernel memory the names and Internet addresses of the +database server machines in the local cell and (optionally) +foreign cells. The appearance of a cell's database server machines +in this list enables the Cache Manager to contact them and to +access files in the cell. Omission of a cell from this list, or +incorrect information about its database server machines, prevents +the Cache Manager from accessing files in it. + +The list of database server machines is transferred into the +kernel from the B file. After +initialization, use the C command to change the +kernel-resident list without having to reboot. + +=item * + +Mounts the root of the AFS filespace on a directory on the +machine's local disk, according to either the first field in the +B file (the default) or the C command's +B<-mountdir> argument. The conventional value is B. + +=item * + +Determines which volume to mount at the root of the AFS file tree. +The default is the volume B; use the B<-rootvol> argument to +override it. Although the base (read/write) form of the volume +name is the appropriate value, the Cache Manager has a bias for +accessing the read-only version of the volume (by convention, +B) if it is available. + +=item * + +Configures the cache on disk (the default) or in machine memory if +the B<-memcache> argument is provided. In the latter case, the C +program allocates space in machine memory for caching, and the +Cache Manager uses no disk space for caching even if the machine +has a disk. + +=item * + +Defines the name of the local disk directory devoted to caching, +when the B<-memcache> argument is not used. If necessary, the C +program creates the directory (its parent directory must already +exist). It does not remove the directory that formerly served this +function, if one exists. + +The second field in the B file is the source +for this name, and the standard value is the B +directory. Use the B<-cachedir> argument to override the value in the +B file. + +=item * + +Sets the size of the cache. The default source for the value is +the third field in the B file, which +specifies a number of kilobytes. + +For a memory cache, the following arguments to the C command +override the value in the B file: + +=over + +=item * + +The B<-blocks> argument, to specify a different number of +kilobyte blocks. + +=item * + +The B<-dcache> and B<-chunksize> arguments together, to set both +the number of dcache entries and the chunk size (see below +for definition of these parameters). In this case, the C +program derives cache size by multiplying the two values. +Using this combination is not recommended, as it requires the +issuer to perform the calculation beforehand to determine the +resulting cache size. + +=item * + +The B<-dcache> argument by itself. In this case, the C +program derives cache size by multiplying the value specified +by the B<-dcache> argument by the default memory cache chunk +size of eight kilobytes. Using this argument is not +recommended, as it requires the issuer to perform the +calculation beforehand to determine the resulting cache size. + +=back + +For satisfactory memory cache performance, the specified value +must leave enough memory free to accommodate all other processes +and commands that can run on the machine. If the value exceeds the +amount of memory available, the C program exits without +initializing the Cache Manager and produces the following message +on the standard output stream: + +afsd: memCache allocation failure at I KB + +where I is how many kilobytes were allocated just before the +failure. + +For a disk cache, use the B<-blocks> argument to the C command to +override the value in the B file. The value specified in +either way sets an absolute upper limit on cache size; values +provided for other arguments (such as B<-dcache> and B<-chunksize>) +never result in a larger cache. The C program rejects any +setting larger than 95% of the partition size, and exits after +generating an error message on the standard output stream, because +the cache implementation itself requires a small amount of disk +space and overfilling the partition can cause the client machine +to panic. + +To change the size of a disk cache after initialization without +rebooting, use the C command; the setting persists +until the C command runs again or the C command +is reissued. The C command does not work for memory +caches. + +=item * + +Sets the size of each cache I, and by implication the amount +of data that the Cache Manager requests at a time from the File +Server (how much data per fetch RPC, since AFS uses partial file +transfer). + +For a disk cache, a chunk is a BI file and this parameter sets the +maximum size to which each one can expand; the default is 64 KB. +For a memory cache, each chunk is a collection of contiguous +memory blocks; the default is size is 8 KB. + +To override the default chunk size for either type of cache, use +the B<-chunksize> argument to provide an integer to be used as an +exponent of two; see the B section for details. For a memory +cache, if total cache size divided by chunk size leaves a +remainder, the C program rounds down the number of dcache +entries, resulting in a slightly smaller cache. + +=item * + +Sets the number of chunks in the cache. For a memory cache, the +number of chunks is equal to the cache size divided by the chunk +size. For a disk cache, the number of chunks (BI files) is set to +the largest of the following unless the B<-files> argument is used to +set the value explicitly: + +=over + +=item * + +100 + +=item * + +1.5 times the result of dividing cache size by chunk size +(I/I * 1.5) + +=item * + +The result of dividing cachesize by 10 KB (I/10240) + +=back + +=item * + +Sets the number of I allocated in machine memory for +storing information about the chunks in the cache. + +For a disk cache, the B file contains one +entry for each BI file. By default, one half the number of these +entries (but not more that 2,000) are duplicated as dcache entries +in machine memory for quicker access. + +For a memory cache, there is no B file so all information +about cache chunks must be in memory as dcache entries. Thus, +there is no default number of dcache entries for a memory cache; +instead, the C program derives it by dividing the cache size by +the chunk size. + +To set the number of dcache entries, use the B<-dcache> argument; the +specified value can exceed the default limit of 2,000. Using this +argument is not recommended for either type of cache. Increasing +the number of dcache entries for a disk cache sometimes improves +performance (because more entries are retrieved from memory rather +than from disk), but only marginally. Using this argument for a +memory cache requires the issuer to calculate the cache size by +multiplying this value by the chunk size. + +=item * + +Sets the number of I entries available in machine memory for +caching status information about cached AFS files. The default is +300; use the B<-stat> argument to override the default. + +=item * + +Randomly selects a file server machine in the local cell as the +source for the correct time. Every five minutes thereafter, the +local clock is adjusted (if necessary) to match the file server +machine's clock. + +Use the B<-nosettime> flag to prevent the C command from selecting +a time standard. This is recommended only on file server machines +that are also acting as clients. File server machines maintain the +correct time using the Network Time Protocol Daemon instead. + +=back + +In addition to setting cache configuration parameters, the C +program starts the following daemons. (On most system types, these +daemons appear as nameless entries in the output of the UNIX C +command.) + +=over + +=item * + +One I daemon, which handles callbacks. It also responds to +the File Server's periodic probes, which check that the client +machine is still alive. + +=item * + +One I daemon, which performs the following tasks: + +=over + +=item * + +Garbage collects obsolete data (for example, expired tokens) +from kernel memory + +=item * + +Synchronizes files + +=item * + +Refreshes information from read-only volumes once per hour + +=item * + +Does delayed writes for NFS clients if the machine is running +the NFS/AFS Translator + +=back + +=item * + +One I daemon, which flushes the cache when free +space is required, by writing cached data and status information +to the File Server. + +=item * + +One I daemon, which sends a probe to the File +Server every few minutes to check that it is still accessible. It +also synchronizes the machine's clock with the clock on a +randomly-chosen file server machine, unless the B<-nosettime> flag is +used. There is always one server connection daemon. + +=item * + +One or more I daemons that improve performance by +pre-fetching files and performing background (delayed) writes of +saved data into AFS. + +The default number of background daemons is two, enough to service +at least five simultaneous users of the machine. To increase the +number, use the B<-daemons> argument. A value greater than six is not +generally necessary. + +=item * + +On some system types, one I daemon, which listens for +incoming RPCs. + +=item * + +On some system types, one I daemon, which reviews the Rx +system's queue of tasks and performs them as appropriate. Most +items in the queue are retransmissions of failed packets. + +=item * + +On machines that run AIX with virtual memory (VM) integration, one +or more I daemons (sometimes called I daemons, which transfer +data between disk and machine memory. The number of them depends +on the setting of the B<-biods> and B<-daemons> arguments: + +=over + +=item * + +If the B<-biods> argument is used, it sets the number of VM +daemons. + +=item * + +If only the B<-daemons> argument is used, the number of VM +daemons is twice the number of background daemons. + +=item * + +If neither argument is used, there are five VM daemons. + +=back + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-blocks> + +Specifies the number of kilobyte blocks to be made available +for caching in the machine's cache directory (for a disk cache) +or memory (for a memory cache), overriding the default defined +in the third field of the B file. For a +disk cache, the value cannot exceed 95% of the space available +in the cache partition. If using a memory cache, do not combine +this argument with the B<-dcache> argument, since doing so can +possibly result in a chunk size that is not an exponent of 2. + +=item B<-files> + +Specifies the number of BI files to create in the cache +directory for a disk cache, overriding the default that is +calculated as described in the B section. Each BI +file accommodates a chunk of data, and can grow to a maximum +size of 64 KB by default. Do not combine this argument with the +B<-memcache> argument. + +=item B<-rootvol> + +Names the read/write volume corresponding to the root directory +for the AFS file tree (which is usually the B directory). +This value overrides the default of the B volume. + +=item B<-stat> + +Specifies the number of entries to allocate in the machine's +memory for recording status information about the AFS files in +the cache. This value overrides the default of 300. + +=item B<-memcache> + +Initializes a memory cache rather than a disk cache. Do not +combine this flag with the B<-files> argument. + +=item B<-cachedir> + +Names the local disk directory to be used as the cache. This +value overrides the default defined in the second field of the +B file. + +=item B<-mountdir> + +Names the local disk directory on which to mount the root of +the AFS filespace. This value overrides the default defined in +the first field of the B file. If a value +other than the B directory is used, the machine cannot +access the filespace of cells that do use that value. + +=item B<-daemons> + +Specifies the number of background daemons to run on the +machine. These daemons improve efficiency by doing prefetching +and background writing of saved data. This value overrides the +default of 2, which is adequate for a machine serving up to +five users. Values greater than B<6> are not generally more +effective than B<6>. + +B: On AIX machines with integrated virtual memory (VM), the +number of VM daemons is set to twice the value of this +argument, if it is provided and the B<-biods> argument is not. If +both arguments are omitted, there are five VM daemons. + +=item B<-nosettime> + +Prevents the Cache Manager from synchronizing its clock with +the clock on a server machine selected at random, by checking +the time on the server machine every five minutes. Use this +flag only on a machine that is already using another time +synchronization protocol (for example, a server machine that is +running the B process). + +=item B<-verbose> + +Generates a detailed trace of the C program's actions on the +standard output stream. + +=item B<-rmtsys> + +Initializes an additional daemon to execute AFS-specific system +calls on behalf of NFS client machines. Use this flag only if +the machine is an NFS/AFS translator machine serving users of +NFS client machines who execute AFS commands. + +=item B<-debug> + +Generates a highly detailed trace of the C program's actions +on the standard output stream. The information is useful mostly +for debugging purposes. + +=item B<-chunksize> + +Sets the size of each cache chunk. The integer provided, which +must be from the range B<0> to B<30>, is used as an exponent on the +number 2. It overrides the default of 16 for a disk cache (2^16 +is 64 KB) and 13 for a memory cache (2^13 is 8 KB). A value of +B<0> or less, or greater than B<30>, sets chunk size to the +appropriate default. Values less than B<10> (which sets chunk size +to a 1 KB) are not recommended. Combining this argument with +the B<-dcache> argument is not recommended because it requires +that the issuer calculate the cache size that results. + +=item B<-dcache> + +Sets the number of dcache entries in memory, which are used to +store information about cache chunks. For a disk cache, this +overrides the default, which is 50% of the number of BI files +(cache chunks). For a memory cache, this argument effectively +sets the number of cache chunks, but its use is not +recommended, because it requires the issuer to calculate the +resulting total cache size (derived by multiplying this value +by the chunk size). Do not combine this argument with the +B<-blocks> argument, since doing so can possibly result in a chunk +size that is not an exponent of 2. + +=item B<-volumes> + +Specifies the number of memory structures to allocate for +storing volume location information. The default value is 50. + +=item B<-biods> + +Sets the number of VM daemons dedicated to performing I/O +operations on a machine running a version of AIX with virtual +memory (VM) integration. If both this argument and the B<-daemons> +argument are omitted, the default is five. If this argument is +omitted but the B<-daemons> argument is provided, the number of VM +daemons is set to twice the value of the B<-daemons> argument. + +B: Provide this argument only on a machine that runs AIX with VM +integration. + +=item B<-prealloc> + +Specifies the number of pieces of memory to preallocate for the +Cache Manager's internal use. The default initial value is 400, +but the Cache Manager dynamically allocates more memory as it +needs it. + +=item B<-confdir> + +Names a directory other than the B directory from +which to fetch the B, B, and B +configuration files. + +=item B<-logfile> + +Is obsolete and has no real effect. It specifies an alternate +file in which to record a type of trace that the Cache Manager +no longer generates; the default value is B. + +=item B<-waitclose> + +Has no effect on the operation of the Cache Manager. The +behavior it affected in previous versions of the Cache Manager, +to perform synchronous writes to the File Server, is now the +default behavior. To perform asynchronous writes in certain +cases, use the C command. + +=item B<-shutdown> + +Shuts down the Cache Manager, but not in the most effective +possible way. Do not use this flag. + +=item B<-enable_peer_stats> + +Activates the collection of Rx statistics and allocates memory +for their storage. For each connection with a specific UDP port +on another machine, a separate record is kept for each type of +RPC (FetchFile, GetStatus, and so on) sent or received. To +display or otherwise access the records, use the Rx Monitoring +API. + +=item B<-enable_process_stats> + +Activates the collection of Rx statistics and allocates memory +for their storage. A separate record is kept for each type of +RPC (FetchFile, GetStatus, and so on) sent or received, +aggregated over all connections to other machines. To display +or otherwise access the records, use the Rx Monitoring API. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The C command is normally included in the machine's AFS +initialization file, rather than typed at the command shell prompt. +For most disk caches, the appropriate form is + + /usr/vice/etc/afsd + + +The following command is appropriate when enabling a machine to act as +an NFS/AFS Translator machine serving more than five users. + + /usr/vice/etc/afsd -daemons 4 -rmtsys + +The following command initializes a memory cache and sets chunk size +to 16 KB (2^14). + + /usr/vice/etc/afsd -memcache -chunksize 14 + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +Do not use the B<-shutdown> parameter. It does not shutdown the Cache +Manager effectively. Instead, halt Cache Manager activity by using the +standard UNIX C command to unmount the AFS root directory (by +convention, B). The machine must then be rebooted to reinitialize +the Cache Manager. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/afsmonitor.pod b/doc/man-pages/pod/afsmonitor.pod new file mode 100644 index 0000000000..19f73cf6da --- /dev/null +++ b/doc/man-pages/pod/afsmonitor.pod @@ -0,0 +1,432 @@ +=head1 NAME + +afsmonitor - Monitors File Servers and Cache Managers + +=head1 SYNOPSIS + +afsmonitor [B] [B<-config> I] +[B<-frequency> I] +[B<-output> I] [B<-detailed>] +[B<-debug> I] +[B<-fshosts> I ...] +[B<-cmhosts> I ...] +[B<-buffers> I] [B<-help>] + +afsmonitor [B] [B<-co> I] +[B<-fr> I] +[B<-o> I] [B<-det>] +[B<-deb> I] +[B<-fs> I ...] +[B<-cm> I ...] +[B<-b> I] [B<-h>] + +=head1 DESCRIPTION + +The C command initializes a program that gathers and displays +statistics about specified File Server and Cache Manager operations. +It allows the issuer to monitor, from a single location, a wide range +of File Server and Cache Manager operations on any number of machines +in both local and foreign cells. + +There are 271 available File Server statistics and 570 available Cache +Manager statistics, listed in the appendix about C statistics +in the IBM AFS Administration Guide. By default, the command displays +all of the relevant statistics for the file server machines named by +the B<-fshosts> argument and the client machines named by the B<-cmhosts> +argument. To limit the display to only the statistics of interest, +list them in the configuration file specified by the B<-config> argument. +In addition, use the configuration file for the following purposes: + +=over + +=item * + +To set threshold values for any monitored statistic. When the +value of a statistic exceeds the threshold, the C command +displays it in reverse video. There are no default threshold +values. + +=item * + +To invoke a program or script automatically when a statistic +exceeds its threshold. The AFS distribution does not include any +such scripts. + +=item * + +To list the file server and client machines to monitor, instead of +using the B<-fshosts> and B<-cmhosts> arguments. + +=back + +For a description of the configuration file, see the B reference page + +=head1 OPTIONS + +=over 4 + +=item B + +Accommodates the command's use of the AFS command parser, and +is optional. + +=item B<-config> I + +Names the configuration file which lists the machines to +monitor, statistics to display, and threshold values, if any. A +partial pathname is interpreted relative to the current working +directory. Provide this argument if not providing the B<-fshosts> +argument, B<-cmhosts> argument, or neither. For instructions on +creating this file, see the preceding B section, and +the section on the C program in the IBM AFS +Administration Guide. + +=item B<-frequency> I + +Specifies in seconds how often the C program probes +the File Servers and Cache Managers. Valid values range from B<1> +to B<86400> (which is 24 hours); the default value is B<60>. This +frequency applies to both File Servers and Cache Managers, but +the C program initiates the two types of probes, and +processes their results, separately. The actual interval +between probes to a host is the probe frequency plus the time +required for all hosts to respond. + +=item B<-output> I + +Names the file to which the C program writes all of +the statistics that it collects. By default, no output file is +created. See the section on the C command in the IBM +AFS Administration Guide for information on this file. + +=item B<-detailed> + +Formats the information in the output file named by B<-output> +argument in a maximally readable format. Provide the B<-output> +argument along with this one. + +=item B<-fshosts> I ... + +Names one or more machines from which to gather File Server +statistics. For each machine, provide either a fully qualified +host name, or an unambiguous abbreviation (the ability to +resolve an abbreviation depends on the state of the cell's name +service at the time the command is issued). This argument can +be combined with the B<-cmhosts> argument, but not with the +B<-config> argument. + +=item B<-cmhosts> I ... + +Names one or more machines from which to gather Cache Manager +statistics. For each machine, provide either a fully qualified +host name, or an unambiguous abbreviation (the ability to +resolve an abbreviation depends on the state of the cell's name +service at the time the command is issued). This argument can +be combined with the B<-fshosts> argument, but not with the +B<-config> argument. + +=item B<-buffers> I + +Is nonoperational and provided to accommodate potential future +enhancements to the program. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The C program displays its data on three screens: + +=over + +=item * + +C: This screen appears automatically when the +C program initializes. It summarizes separately for File +Servers and Cache Managers the number of machines being monitored +and how many of them have I (statistics that have exceeded +their thresholds). It then lists the hostname and number of alerts +for each machine being monitored, indicating if appropriate that a +process failed to respond to the last probe. + +=item * + +C: This screen displays File Server statistics for each +file server machine being monitored. It highlights statistics that +have exceeded their thresholds, and identifies machines that +failed to respond to the last probe. + +=item * + +C: This screen displays Cache Manager statistics for +each client machine being monitored. It highlights statistics that +have exceeded their thresholds, and identifies machines that +failed to respond to the last probe. + +=back + +Fields at the corners of every screen display the following +information: + +=over + +=item * + +In the top left corner, the program name and version number. + +=item * + +In the top right corner, the screen name, current and total page +numbers, and current and total column numbers. The page number +(for example, p. 1 of 3) indicates the index of the current page +and the total number of (vertical) pages over which data is +displayed. The column number (for example, c. 1 of 235) indicates +the index of the current leftmost column and the total number of +columns in which data appears. (The symbol >>> indicates that +there is additional data to the right; the symbol <<< indicates +that there is additional data to the left.) + +=item * + +In the bottom left corner, a list of the available commands. Enter +the first letter in the command name to run that command. Only the +currently possible options appear; for example, if there is only +one page of data, the C and C commands, which scroll the +screen up and down respectively, do not appear. For descriptions +of the commands, see the following section about navigating the +display screens. + +=item * + +In the bottom right corner, the C field reports how many +times the program has probed File Servers (C), Cache Managers +(C), or both. The counts for File Servers and Cache Managers can +differ. The C field reports how often the program sends probes. + +=back + +=head1 Navigating the afsmonitor Display Screens + +As noted, the lower left hand corner of every display screen displays +the names of the commands currently available for moving to alternate +screens, which can either be a different type or display more +statistics or machines of the current type. To execute a command, +press the lowercase version of the first letter in its name. Some +commands also have an uppercase version that has a somewhat different +effect, as indicated in the following list. + +=over + +=item B + +Switches to the C screen. Available only on the +C and C screens. + +=item B + +Switches to the C screen. Available only on the +C and the C screens. + +=item B + +Scrolls horizontally to the left, to access the data columns +situated to the left of the current set. Available when the <<< +symbol appears at the top left of the screen. Press uppercase B +to scroll horizontally all the way to the left (to display the +first set of data columns). + +=item B + +Scrolls down vertically to the next page of machine names. +Available when there are two or more pages of machines and the +final page is not currently displayed. Press uppercase B to +scroll to the final page. + +=item B + +Switches to the C screen. Available only on the +C and C screens. + +=item B + +Scrolls up vertically to the previous page of machine names. +Available when there are two or more pages of machines and the +first page is not currently displayed. Press uppercase B

to +scroll to the first page. + +=item B + +Scrolls horizontally to the right, to access the data columns +situated to the right of the current set. This command is +available when the >>> symbol appears at the upper right of the +screen. Press uppercase B to scroll horizontally all the way to +the right (to display the final set of data columns). + +=back + +=head1 The System Overview Screen + +The C screen appears automatically as the C +program initializes. This screen displays the status of as many File +Server and Cache Manager processes as can fit in the current window; +scroll down to access additional information. + +The information on this screen is split into File Server information +on the left and Cache Manager information on the right. The header for +each grouping reports two pieces of information: + +=over + +=item * + +The number of machines on which the program is monitoring the +indicated process + +=item * + +The number of alerts and the number of machines affected by them +(an I means that a statistic has exceeded its threshold or a +process failed to respond to the last probe) + +=back + +A list of the machines being monitored follows. If there are any +alerts on a machine, the number of them appears in square brackets to +the left of the hostname. If a process failed to respond to the last +probe, the letters C (probe failure) appear in square brackets to the +left of the hostname. + +=head1 The File Servers Screen + +The C screen displays the values collected at the most +recent probe for File Server statistics. + +A summary line at the top of the screen (just below the standard +program version and screen title blocks) specifies the number of +monitored File Servers, the number of alerts, and the number of +machines affected by the alerts. + +The first column always displays the hostnames of the machines running +the monitored File Servers. + +To the right of the hostname column appear as many columns of +statistics as can fit within the current width of the display screen +or window; each column requires space for 10 characters. The name of +the statistic appears at the top of each column. If the File Server on +a machine did not respond to the most recent probe, a pair of dashes +(--) appears in each column. If a value exceeds its configured +threshold, it is highlighted in reverse video. If a value is too large +to fit into the allotted column width, it overflows into the next row +in the same column. + +=head1 The Cache Managers Screen + +The Cache Managers screen displays the values collected at the most +recent probe for Cache Manager statistics. + +A summary line at the top of the screen (just below the standard +program version and screen title blocks) specifies the number of +monitored Cache Managers, the number of alerts, and the number of +machines affected by the alerts. + +The first column always displays the hostnames of the machines running +the monitored Cache Managers. + +To the right of the hostname column appear as many columns of +statistics as can fit within the current width of the display screen +or window; each column requires space for 10 characters. The name of +the statistic appears at the top of each column. If the Cache Manager +on a machine did not respond to the most recent probe, a pair of +dashes (--) appears in each column. If a value exceeds its configured +threshold, it is highlighted in reverse video. If a value is too large +to fit into the allotted column width, it overflows into the next row +in the same column. + +=head1 Writing to an Output File + +Include the B<-output> argument to name the file into which the +C program writes all of the statistics it collects. The +output file can be useful for tracking performance over long periods +of time, and enables the administrator to apply post-processing +techniques that reveal system trends. The AFS distribution does not +include any post-processing programs. + +The output file is in ASCII format and records the same information as +the File Server and Cache Manager display screens. Each line in the +file uses the following format to record the time at which the +C program gathered the indicated statistic from the Cache +Manager (C) or File Server (C) running on the machine called +I. If a probe failed, the error code B<-1> appears in the +I field. + +I

for day, and I for year) and an optional +portion (I for hours and I for minutes). + +Omit the I:I portion to use the default of midnight (00:00 +hours), or provide a value in 24-hour format (for example, +B<20:30> is 8:30 p.m.). Valid values for the year range from B<1970> +to B<2037>; higher values are not valid because the latest +possible date in the standard UNIX representation is in +February 2038. The command interpreter automatically reduces +later dates to the maximum value. + +Relative expiration dates have the following format: + +[B] [IB] [IB] [IB] + +where the optional word B is followed by at least one of a +number of years (maximum B<9999>) followed by the letter B, a +number of months (maximum B<12>) followed by the letter B, or a +number of days (maximum B<31>) followed by the letter B. If +providing more than one of the three, list them in the +indicated order. If the date that results from adding the +relative expiration value to a dump's creation time is later +than the latest possible date in the UNIX time representation, +the Backup System automatically reduces it to that date. + +=over + +=item B: + +A plus sign follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition to be associated with each dump level specified by the +B<-dump> argument. + +=back + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command defines a full dump called B with a relative +expiration date of one year: + + backup adddump -dump /1999 -expires in 1y + +The following command defines an incremental dump called +B with a relative expiration date of 13 days: + + backup adddump -dump /sunday1/monday1 -expires in 13d + +The following command defines two dump incremental dump levels, +B and B. Their parent, the full dump level +B, must already exist. The expiration date for both levels is +12:00 a.m. on 1 January 2000. + + backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_addhost.pod b/doc/man-pages/pod/backup_addhost.pod new file mode 100644 index 0000000000..108d96a3f2 --- /dev/null +++ b/doc/man-pages/pod/backup_addhost.pod @@ -0,0 +1,118 @@ +=head1 NAME + +backup addhost - Adds a Tape Coordinator entry to the Backup Database + +=head1 SYNOPSIS + +backup addhost B<-tapehost> I [B<-portoffset> I] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup addh B<-t> I [B<-p> I] +[B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command creates a Tape Coordinator entry in the +Backup Database. The entry records + +=over + +=item * + +The host name of the Tape Coordinator machine where the Tape +Coordinator (B) process runs, as specified with the B<-tapehost> +argument. + +=item * + +The Tape Coordinator's port offset number, as specified with the +B<-portoffset> argument. An entry for the port offset must also +appear in the B file on the Tape +Coordinator machine, where it is mapped to a UNIX device name (for +a tape device) or pathname (for a backup data file). + +=back + +Each Tape Coordinator must have its own port offset number, and the +command fails if a Backup Database entry already exists for the +requested port offset number. To display existing Tape Coordinator +entries, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-tapehost> I + +Specifies the fully-qualified hostname of the machine for which +to create a Tape Coordinator entry in the Backup Database. The +machine must have an entry in either the cell's naming service +(such as the Domain Name Service) or the host file (B +or equivalent) on the machine where the command is issued. + +=item B<-portoffset> I + +Specifies the Tape Coordinator's port offset number. Provide an +integer from the range B<0> through B<58510>, or omit this argument +to use the default value of B<0> (zero). The value must match the +port offset number recorded for the same combination of Tape +Coordinator and tape device or file in the +B file on the Tape Coordinator machine +named by the B<-tapehost> argument. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command creates an entry in the Backup Database that +assigns port offset number 4 to a Tape Coordinator running on the +machine B: + + backup addhost -tapehost backup1.abc.com -portoffset 4 + +The following command creates a Backup Database entry that assigns +port offset number 0 to a Tape Coordinator on the machine +B: + + backup addhost backup3.abc.com + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_addvolentry.pod b/doc/man-pages/pod/backup_addvolentry.pod new file mode 100644 index 0000000000..5839881d76 --- /dev/null +++ b/doc/man-pages/pod/backup_addvolentry.pod @@ -0,0 +1,203 @@ +=head1 NAME + +backup addvolentry - Defines a volume entry in a volume set + +=head1 SYNOPSIS + +backup addvolentry B<-name> I B<-server> I +B<-partition> I +B<-volumes> I +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup addvole B<-n> I B<-s> I B<-p> I +B<-v> I +[B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command adds a volume entry definition to the +existing volume set named by the B<-name> argument. A volume entry +definition can match one or more volumes, depending on the combination +of the B<-server>, B<-partition>, and B<-volumes> arguments. + +For the B<-server> and B<-partition> arguments, provide either + +=over + +=item * + +The name of one machine or partition + +=item * + +The metacharacter expression B<.*> (period and asterisk), which +matches every machine name or partition name in the Volume +Location Database (VLDB). + +=back + +For the B<-volumes> argument, specify a combination of alphanumeric +characters and one or more metacharacters to wildcard part or all of +the volume name. The B section lists the acceptable +metacharacters. + +=head1 OPTIONS + +=over 4 + +=item B<-name> + +Names the volume set to which to add this volume entry +definition. The volume set must already exist (use the C command to create it). + +=item B<-server> + +Defines the set of one or more file server machines that house +the volumes in the volume entry. Provide either one +fully-qualified hostname (such as B) or the +metacharacter expression B<.*> (period and asterisk), which +matches all machine names in the VLDB. + +=item B<-partition> + +Defines the set of one or more partitions that house the +volumes in the volume entry. Provide either one complete +partition name (such as B) or the metacharacter +expression B<.*> (period and asterisk), which matches all +partition names. + +=item B<-volumes> + +Defines the set of one or more volumes included in the volume +entry. Specify the volumes by name, by using any combination of +regular alphanumeric characters and one or more of the +following metacharacter expressions: + +=over + +=item B<.> + +The period matches any single character. + +=item B<*> + +The asterisk matches zero or more instances of the +preceding character. Combine it with any other +alphanumeric character or metacharacter. + +=item B<[ ]> + +Square brackets around a list of characters match a +single instance of any of the characters, but no other +characters; for example, B<[abc]> matches a single B or B or +B, but not B or B. This expression can be combined with +the asterisk. + +=item B<^> + +The caret, when used as the first character in a +square-bracketed set, designates a match with any single +character I the characters that follow it; for +example, B<[^a]> matches any single character except +lowercase B. This expression can be combined with the +asterisk. + +=item B<\> + +A backslash preceding any of the metacharacters in this +list makes it match its literal value only. For example, +the expression B<\.> (backslash and period) matches a single +period, B<\*> a single asterisk, and B<\\> a single backslash. +Such expressions can be combined with the asterisk (for +example, B<\.*> matches any number of periods). + +=back + +Perhaps the most common metacharacter expression is the period +followed by an asterisk (B<.*>). This expression matches any +string of any length, because the period matches any character +and the asterisk means any number of that character. As +mentioned, it is the only acceptable metacharacter expression +for the B<-server> and B<-partition> arguments. In a volume +definition it can stand alone (in which case it matches every +volume listed in the VLDB), or can combine with regular +characters. The following example matches any volume name that +begins with the string B and ends with B: + +B + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command adds a volume entry to the volume set called +B. The entry matches all volumes on any machine or partition whose +names begin with the string B followed by a period: + + backup> addvolentry sys .* .* sun4x_56\..* + +The following command adds a volume entry to the volume set called +fs2, to match all volumes on the /vicepb partition of file server +machine fs2.abc.com. Because it is issued at the shell prompt, double +quotes surround the metacharacters in the -volumes argument. (The +command is shown here on two lines only for legibility reasons.) + + backup addvolentry -name fs2 -server fs2.abc.com \ + -partition /vicepb -volumes ".*" + +The chapter in the IBM AFS Administration Guide about configuring the +AFS Backup System presents additional examples as well as advice on +grouping volumes. + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +It is best to issue this command in interactive mode. If issuing it at +the shell prompt, enclose any strings containing metacharacters in +double quotes, or escape the metacharacters with other delimiters, to +prevent the shell from interpreting them. Adding volume entries to a +temporary volume set is possible only within the interactive session +in which the volume set was created. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_addvolset.pod b/doc/man-pages/pod/backup_addvolset.pod new file mode 100644 index 0000000000..7c86bc68d0 --- /dev/null +++ b/doc/man-pages/pod/backup_addvolset.pod @@ -0,0 +1,114 @@ +=head1 NAME + +backup addvolset - Creates a new (empty) volume set + +=head1 SYNOPSIS + +backup addvolset B<-name> I [B<-temporary>] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup addvols B<-n> I [B<-t>] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command creates a new volume set, by default +adding it to the Backup Database. It is best that the volume set's +name indicate the volume set's contents; for example, define the +volume entries in the user volume set to match all user volumes. The +volume set name must be unique within the Backup Database of the local +cell. + +After issuing this command, issue the C command to +define the volume entries in the volume set. + +Sometimes it is convenient to create volume sets without recording +them permanently in the Backup Database, for example when using the +C command to restore a group of volumes that were +not necessarily backed up together. To create a I volume set, +include the B<-temporary> flag. A temporary volume set exists only during +the lifetime of the current interactive session, so the flag is +effective only when used during an interactive session (opened by +issuing the C command). If it is included when the +command is issued at the regular command shell prompt, the command +appears to succeed, but the volume set is not created. As noted, a +temporary volume set ceases to exist when the current interactive +session ends, or use the C command to delete it before +that. + +One advantage of temporary volume sets is that the C +command, and any C commands subsequently used to add +volume entries to it, complete more quickly than for regular volume +sets, because no records are created in the Backup Database. + +=head1 OPTIONS + +=over 4 + + +=item B<-name> I + +Names the new volume set. The name can include up to 31 of any +character other than the period. Avoid other metacharacters as +well. + + +=item B<-temporary> + +Creates a volume set that exists only within the context of the +current interactive session. It is not added to the Backup +Database. + + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command creates a volume set called sys: + + backup addvolset sys + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_apropos.pod b/doc/man-pages/pod/backup_apropos.pod new file mode 100644 index 0000000000..ac694967e9 --- /dev/null +++ b/doc/man-pages/pod/backup_apropos.pod @@ -0,0 +1,72 @@ +=head1 NAME + +backup apropos - Displays each help entry containing a keyword string + +=head1 SYNOPSIS + +backup apropos B<-topic> I [B<-help>] + +backup ap B<-t> I [B<-h>] + +=head1 DESCRIPTION + +The C command displays the first line of the online help +entry for any C command that has in its name or short description +the string specified by the B<-topic> argument. + +To display the syntax for a command, use the C command. + +=head1 OPTIONS + +=over 4 + + +=item B<-topic> I + +Specifies the keyword string to match, in lowercase letters +only. If the string is more than a single word, surround it +with double quotes (" ") or other delimiters. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of a command's online help entry names it and briefly +describes its function. This command displays the first line for any +C command where the string specified with the B<-topic> argument is +part of the command name or first line. + +=head1 EXAMPLES + +The following example lists all C commands that include the word +B in their names or short descriptions: + + backup apropos tape + labeltape: label a tape + readlabel: read the label on tape + scantape: dump information recovery from tape + status: get tape coordinator status + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_dbverify.pod b/doc/man-pages/pod/backup_dbverify.pod new file mode 100644 index 0000000000..e089b76efa --- /dev/null +++ b/doc/man-pages/pod/backup_dbverify.pod @@ -0,0 +1,144 @@ +=head1 NAME + +backup dbverify - Checks the integrity of the Backup Database + +=head1 SYNOPSIS + +backup dbverify [B<-detail>] [B<-localauth>] [B<-cell> I] [B<-help>] + +backup db [B<-d>] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command checks the integrity of the Backup +Database. The command's output indicates whether the Backup Database +is damaged (data is corrupted) or not. If the Backup Database is +undamaged, it is safe to continue using it. If it is corrupted, +discontinue any backup operations until it is repaired. + +=head1 OPTIONS + +=over 4 + +=item B<-detail> + +Reports the number of orphaned blocks found, any +inconsistencies, and the name of the server machine running the +Backup Server that is checking its copy of the database. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The command displays one of the following two messages: + +=over + +=item B + +The database is undamaged and can be used. + +=item B + +The database is damaged. You can use the C command +to repair many kinds of corruption as it creates a backup copy. +For more detailed instructions, see the IBM AFS Administration +Guide chapter about performing backup operations. + +=back + +The B<-detail> flag provides additional information: + +=over + +=item * + +The number of I found. These are ranges of memory that +the Backup Server preallocated in the database but cannot use. +Orphan blocks do not interfere with database access, but do waste +disk space. To free the unusable space, dump the database to tape +by using the C command, and then restore it by using +the C command. + +=item * + +Any inconsistencies in the database, such as invalid hostnames for +Tape Coordinator machines. + +=item * + +The name of the database server machine on which the Backup +Database was checked, designated as the Database checker. For a +detailed trace of the verification operation, see the +B file on the indicated machine. You can use +the C command to display it. + +=back + +=head1 EXAMPLES + +The following command confirms that the Backup Database is undamaged: + + backup dbverify + Database OK + +The following command confirms that the Backup Database is undamaged +and that it has no orphan blocks or invalid Tape Coordinator entries. +The Backup Server running on the machine B checked its copy +of the Database. + + backup dbverify -detail + Database OK + Orphan blocks 0 + Database checker was db1.abc.com + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +While this command runs, no other backup operation can access the +Backup Database; the other commands do not run until this command +completes. Avoid issuing this command when other backup operations are +likely to run. The C command repairs some types of +corruption. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_deldump.pod b/doc/man-pages/pod/backup_deldump.pod new file mode 100644 index 0000000000..bbd8c065f9 --- /dev/null +++ b/doc/man-pages/pod/backup_deldump.pod @@ -0,0 +1,78 @@ +=head1 NAME + +backup deldump - Deletes a dump level from the Backup Database + +=head1 SYNOPSIS + +backup deldump B<-dump> I [B<-localauth>] +[B<-cell> I] [B<-help>] + +backup deld B<-d> I [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command deletes the indicated dump level and all of +its child dump levels from the dump hierarchy in the Backup Database. +Use the C command to display the dump hierarchy. + +=head1 OPTIONS + +=over 4 + + +=item B<-dump> I + +Specifies the complete pathname of the dump level to delete. + + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command deletes the dump level B from the +dump hierarchy, along with any of its child dump levels. + + backup deldump /sunday1/monday1 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_deletedump.pod b/doc/man-pages/pod/backup_deletedump.pod new file mode 100644 index 0000000000..ad3fff33db --- /dev/null +++ b/doc/man-pages/pod/backup_deletedump.pod @@ -0,0 +1,212 @@ +=head1 NAME + +backup deletedump - Deletes one or more dump records from the Backup Database + +=head1 SYNOPSIS + +backup deletedump [B<-dumpid> I [I ...]] [B<-from> I ...] +[B<-to> I ...] [B<-localauth>] [B<-cell> I] [B<-help>] + +backup dele [B<-d> I [I ...]] [B<-f> I [I ...]] +[B<-t> I [I ...]] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command deletes one or more dump records from +the Backup Database. Either use the B<-dumpid> argument to specify the +dump ID number of one or more dumps, or use the B<-from> and B<-to> +arguments to delete the records for all regular dumps created during +the time period bracketed by the specified values. + +Use this command to remove dump records that are incorrect (possibly +because a dump operation was interrupted or failed), or that +correspond to dumps that are expired or otherwise no longer needed. + +=head1 OPTIONS + +=over 4 + +=item B<-dumpid> I [I ...] + +Specifies the dump ID of each dump record to delete. The +corresponding dumps must be initial dumps; it is not possible +to delete appended dump records directly, but only by deleting +the record of their associated initial dump. Using this +argument is the only way to delete records of Backup Database +dumps (created with the C command). + +Provide either this argument or the B<-to> (and optionally B<-from>) +argument. + +=item B<-from> I ... + +Specifies the beginning of a range of dates; the record for any +dump created during the indicated period of time is deleted. + +Omit this argument to indicate the default of midnight (00:00 +hours) on 1 January 1970 (UNIX time zero), or provide a date +value in the format I/I
/I [I:I]. The month (I), day +(I
), and year (I) are required. The hour and minutes +(I:I) are optional, but if provided must be in 24-hour format +(for example, the value B<14:36> represents 2:36 p.m.). If +omitted, the time defaults to midnight (00:00 hours). + +The B<-to> argument must be provided along with this one. + +=over + +=item B + +A ... follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition. + +=back + +=item B<-to> I ... + +Specifies the end of a range of dates; the record of any dump +created during the range is deleted from the Backup Database. + +Provide either the value B to indicate the current date and +time, or a date value in the same format as for the B<-from> +argument. Valid values for the year (I) range from B<1970> to +B<2037>; higher values are not valid because the latest possible +date in the standard UNIX representation is in February 2038. +The command interpreter automatically reduces any later date to +the maximum value. + +If the time portion (I:I) is omitted, it defaults to 59 +seconds after midnight (00:00:59 hours). Similarly, the C +command interpreter automatically adds 59 seconds to any time +value provided. In both cases, adding 59 seconds compensates +for how the Backup Database and C command +represent dump creation times in hours and minutes only. For +example, the Database records a creation timestamp of 20:55 for +any dump operation that begins between 20:55:00 and 20:55:59. +Automatically adding 59 seconds to a time thus includes the +records for all dumps created during that minute. + +Provide either this argument, or the B<-dumpid> argument. This +argument is required if the B<-from> argument is provided. + +B: Specifying the value B for this argument when the +B<-from> argument is omitted deletes all dump records from the +Backup Database (except for Backup Database dump records +created with the C command). + +=over + +=item B + +A ... follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition. + +=back + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + + +=item B<-cell> + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +At the conclusion of processing, the output lists the dump IDs of all +dump records deleted in the following format: + + The following dumps were deleted: + dump ID 1 + dump ID 2 + etc. + +=head1 EXAMPLES + +The following command deletes the dump record with dump ID 653777462, +and for any appended dumps associated with it: + + backup deletedump -dumpid 653777462 + The following dumps were deleted: + 653777462 + +The following command deletes the Backup Database record of all dumps +created between midnight on 1 January 1997 and 23:59:59 hours on 31 +December 1997: + + backup deletedump -from 01/01/1997 -to 12/31/1997 + The following dumps were deleted: + 598324045 + 598346873 + ... + ... + 653777523 + 653779648 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +The only way to remove the dump record for an appended dump is to +remove the record for its initial dump, and doing so removes the +records for all of the initial dump's associated appended dumps. + +The only way to remove the record for a Backup Database dump (created +with the C command) is to specify its dump ID number with +the B<-dumpid> argument. Using the B<-from> and B<-to> arguments never removes +database dump records. + +Removing records of a dump makes it impossible to restore data from +the corresponding tapes or from any dump that refers to the deleted +dump as its parent, directly or indirectly. That is, restore +operations must begin with the full dump and continue with each +incremental dump in order. If the records for a specific dump are +removed, it is not possible to restore data from later incremental +dumps unless the deleted records are restored by running the C command with the B<-dbadd> flag. + +If a dump set contains any dumps that were created outside the time +range specified by the B<-from> and B<-to> arguments, the command does not +delete any of the records associated with the dump set, even if some +of them represent dumps created during the time range. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_delhost.pod b/doc/man-pages/pod/backup_delhost.pod new file mode 100644 index 0000000000..f842843e64 --- /dev/null +++ b/doc/man-pages/pod/backup_delhost.pod @@ -0,0 +1,93 @@ +=head1 NAME + +backup delhost - Deletes a Tape Coordinator entry from the Backup Database + +=head1 SYNOPSIS + +backup delhost B<-tapehost> I [B<-portoffset> I] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup delh B<-t> I [B<-p> I] +[B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command deletes the indicated Tape Coordinator +entry from the Backup Database. It is then impossible to submit backup +operations to that Tape Coordinator, even if it is still running. To +keep configuration information consistent, also remove the +corresponding entry from the B file on the +Tape Coordinator machine. + +To list the Tape Coordinator machines and port offsets defined in the +Backup Database, issue the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-tapehost> I + +Specifies the hostname of the machine housing the Tape +Coordinator to delete. + +=item B<-portoffset> I + +Specifies the port offset number of the Tape Coordinator to +delete. If omitted, it defaults to B<0>. If provided, it is an +integer between B<0> (zero) and B<58510>, and must match the port +offset number assigned to the same combination of Tape +Coordinator and tape device or file in the +B file on the Tape Coordinator machine +indicated by the B<-tapehost> argument. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command deletes the Backup Database entry for the Tape +Coordinator with port offset 2 on the Tape Coordinator machine +B: + + backup delhost -tapehost backup3.abc.com -portoffset 2 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_delvolentry.pod b/doc/man-pages/pod/backup_delvolentry.pod new file mode 100644 index 0000000000..f1f3826730 --- /dev/null +++ b/doc/man-pages/pod/backup_delvolentry.pod @@ -0,0 +1,93 @@ +=head1 NAME + +backup delvolentry - Deletes a volume entry from a volume set + +=head1 SYNOPSIS + +backup delvolentry B<-name> I B<-entry> I +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup delvole B<-n> I B<-e> I +[B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command deletes the indicated volume entry from +the volume set specified with the B<-name> argument. Use the B<-entry> +argument to identify the volume entry by its index number. To display +the index numbers, use the C command. + +If there are any remaining volume entries with index numbers higher +than the deleted entry, their indexes are automatically decremented to +eliminate any gaps in the indexing sequence. + +=head1 OPTIONS + +=over 4 + +=item B<-name> I + +Names the volume set from which to delete a volume entry. + +=item B<-entry> I + +Specifies the index number of the volume entry to delete. Use +the C command to display the index numbers for +a volume set's volume entries. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command deletes the fourth volume entry from the volume +set called B: + + backup delvolentry -name sys -entry 4 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Deleting volume entries from a temporary volume set is possible only +within the interactive session in which the volume set was created. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_delvolset.pod b/doc/man-pages/pod/backup_delvolset.pod new file mode 100644 index 0000000000..025e3ab38f --- /dev/null +++ b/doc/man-pages/pod/backup_delvolset.pod @@ -0,0 +1,83 @@ +=head1 NAME + +backup delvolset - Deletes one or more volume sets from the Backup Database + +=head1 SYNOPSIS + +backup delvolset B<-name> I [I ...] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup delvols B<-n> I [I ...] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command deletes each volume set named by the +B<-name> argument, and the volume entries each contains, from the Backup +Database. The C command lists the volume sets (and +their volume entries) currently defined in the Backup Database. + +=head1 OPTIONS + +=over 4 + +=item B<-name> I [I ...] + +Names each volume set to delete. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command deletes the volume set called user and all +volume entries in it: + + backup delvolset user + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Deleting a temporary volume set is possible only within the +interactive session in which it was created. Exiting the interactive +session also destroys the temporary volume set automatically. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_diskrestore.pod b/doc/man-pages/pod/backup_diskrestore.pod new file mode 100644 index 0000000000..31bbdef993 --- /dev/null +++ b/doc/man-pages/pod/backup_diskrestore.pod @@ -0,0 +1,280 @@ +=head1 NAME + +backup diskrestore - Restores the entire contents of a partition + +=head1 SYNOPSIS + +backup diskrestore B<-server> I +B<-partition> I +[B<-portoffset> I [I ...]] +[B<-newserver> I] +[B<-newpartition> I] +[B<-extension> I] +[B<-n>] [B<-localauth>] [B<-cell> I] [B<-help>] + +backup di B<-s> I B<-pa> I +[B<-po> I [I ...]] [B<-news> I] +[B<-newp> I] [B<-e> I] +[B<-n>] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command restores all of the volumes for which +the Volume Location Database (VLDB) lists a read/write site on the +partition specified with the B<-server> and B<-partition> arguments. It is +useful if a disk or machine failure corrupts or destroys the data on +an entire partition. (To restore any read-only or backup volumes that +resided on the partition, use the C and C commands, +respectively, after restoring the read/write version.) + +If restoring only selected volumes to a single site, it is usually +more efficient to use the C command. To restore +multiple volumes to many different sites, use the C command. + +(If the B instruction appears in the +BI<_device_name> file on the Tape Coordinator machine +associated with the specified port offset, then the Backup System +restores data from the backup data file listed for that port offset in +the Tape Coordinator's B file, instead of +from tape. For the sake of clarity, the following text refers to tapes +only, but the Backup System handles backup data files in much the same +way.) + +The Backup System determines whether the read/write or backup version +of each volume was dumped more recently, and restores the dumps of +that version, starting with the most recent full dump. It resets the +creation timestamp of each restored volume to the date and time at +which it begins restoring the volume (the creation timestamp appears +in the Creation field of the output from the C and C commands). + +If all of the full and incremental dumps of all relevant volumes were +not written on compatible tape devices, use the B<-portoffset> argument +to list multiple port offset numbers in the order in which the tapes +are needed (first list the port offset for the full dump, second the +port offset for the level 1 incremental dump, and so on). This implies +that the full dumps of all relevant volumes must have been written to +a type of tape that the first Tape Coordinator can read, the level 1 +incremental dumps to a type of tape the second Tape Coordinator can +read, and so on. If dumps are on multiple incompatible tape types, use +the C command to restore individual volumes, or the +C command after defining groups of volumes that +were dumped to compatible tape types. For further discussion, see the +IBM AFS Administration Guide. + +By default, the Backup System restores the contents of the specified +partition to that same partition. To restore the contents to an +alternate site, combine the following options as indicated. The Backup +System removes each volume from the original site, if it still exists, +and records the change of site in the VLDB. + +=over + +=item * + +To restore to a different partition on the same file server +machine, provide the B<-newpartition> argument. + +=item * + +To restore to the partition with the same name on a different file +server machine, provide the B<-newserver> argument. + +=item * + +To restore to a completely different site, combine the B<-newserver> +and B<-newpartition> arguments. + +=back + +By default, the Backup System overwrites the contents of existing +volumes with the restored data. To create a new volume to house the +restored data instead, use the B<-extension> argument. The Backup System +creates the new volume at the site designated by the B<-newserver> and +B<-newpartition> arguments if they are used or the B<-server> and B<-partition> +arguments otherwise. It derives the volume name by adding the +extension to the read/write base name listed in the VLDB, and creates +a new VLDB entry. The command does not affect the existing volume in +any way. However, if a volume with the specified extension also +already exists, the command overwrites it. + +To print out a list of the tapes containing the needed dumps, without +actually performing the restore operation, include the B<-n> flag along +with the other options to be used on the actual command. + +The Tape Coordinator's default response to this command is to access +the first tape it needs by invoking the B instruction in the local +BI<_device_name> file, or by prompting the backup operator to insert +the tape if there is no B instruction. However, if the B instruction appears in the BI<_device_name> file, or if the issuer +of the C command included the B<-noautoquery> flag, the Tape +Coordinator instead expects the tape to be in the device already. If +it is not, or is the wrong tape, the Tape Coordinator invokes the +B instruction or prompts the operator. It also invokes the B +instruction or prompts for any additional tapes needed to complete the +restore operation; the backup operator must arrange to provide them. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Names the file server machine that the VLDB lists as the site +of the volumes that need to be restored. + +=item B<-partition> I + +Names the partition that the VLDB lists as the site of the +volumes that need to be restored. + +=item B<-portoffset> I [I ...] + +Specifies one or more port offset numbers (up to a maximum of +128), each corresponding to a Tape Coordinator to use in the +operation. If there is more than one value, the Backup System +uses the first one when restoring the full dump of each volume, +the second one when restoring the level 1 incremental dump of +each volume, and so on. It uses the final value in the list +when restoring dumps at the corresponding depth in the dump +hierarchy and at all lower levels. + +Provide this argument unless the default value of 0 (zero) is +appropriate for all dumps. If B<0> is just one of the values in +the list, provide it explicitly in the appropriate order. + +=item B<-newserver> I + +Names an alternate file server machine to which to restore the +volumes. If this argument is omitted, the volumes are restored +to the file server machine named by the B<-server> argument. + +=item B<-newpartition> I + +Names an alternate partition to which to restore the data. If +this argument is omitted, the volumes are restored to the +partition named by the B<-partition> argument. + +=item B<-extension> I + +Creates a new volume for each volume being restored, to house +the restored data. The Backup System derives the new volume's +name by appending the specified string to the read/write base +name listed in the VLDB, and creates a new VLDB volume entry. +The Backup System preserves the contents of the volumes on the +partition, if any still exist. Any string other than B<.readonly> +or B<.backup> is acceptable, but the combination of the base name +and extension cannot exceed 22 characters in length. To use a +period to separate the extension from the name, specify it as +the first character of the string (as in B<.rst>, for example). + +=item B<-n> + +Displays a list of the tapes necessary to perform the requested +restore, without actually performing the operation. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If a tape error occurs during the restore operation, the Tape +Coordinator displays the following messages: + + Restore operation on volume name failed due to tape error + Do you want to continue (y/n)? + +where I is the name of the volume that was being restored when the +tape error occurred. Enter the value B to continue the operation +without restoring the indicated volume or the value B to terminate the +operation. In the latter case, the operator can then attempt to +determine the cause of the tape error. + +If the issuer includes the B<-n> flag with the command, the following +string appears at the head of the list of the tapes necessary to +perform the restore operation: + + Tapes needed: + +=head1 EXAMPLES + +The following command restores the volumes for which the VLDB lists a +read/write site on the B partition of the machine B. +The Tape Coordinator associated with port offset 3 performs the +operation. + + backup diskrestore -server fs5.abc.com -partition /vicepd -portoffset 3 + +The following command restores the volumes for which the VLDB lists a +read/write site on the B partition of the machine B to +a new site: the B partition on the machine B. The Tape +Coordinator associated with port offset 0 performs the operation. (The +command appears here on two lines only for legibility.) + + backup diskrestore -server fs1.abc.com -partition /vicepb \ + -newserver fs3.abc.com -newpartition /vicepa + +The following command lists the tapes required to restore the volumes +for which the VLDB lists a read/write site on the B partition of +the machine B: + + backup diskrestore -server fs4.abc.com -partition /vicepm -n + Tapes needed: + user.sunday1.1 + user.sunday1.2 + user.monday1.1 + user.tuesday1.1 + user.wednesday1.1 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server or Volume Location (VL) Server is +running, and on every file server machine that houses an affected +volume. If the B<-localauth> flag is included, the issuer must instead be +logged on to a server machine as the local superuser B. + +=head1 CAVEATS + +If issuing this command to recover data after a disk crash or other +damage, be sure not to issue the C command first. Doing so +destroys the VLDB record of the volumes that resided on the partition. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_dump.pod b/doc/man-pages/pod/backup_dump.pod new file mode 100644 index 0000000000..3abed19c21 --- /dev/null +++ b/doc/man-pages/pod/backup_dump.pod @@ -0,0 +1,547 @@ +=head1 NAME + +backup dump - Creates a dump (dumps a volume set at a particular dump level) + +=head1 SYNOPSIS + +backup dump [B<-volumeset> I] [B<-dump> I] +[B<-portoffset> I] [B<-at> I ...] +[B<-append>] [B<-n>] [B<-file> I] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup dump [B<-v> I] [B<-d> I] +[B<-p> I] [B<-at> I ...] +[B<-ap>] [B<-n>] [B<-f> I] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command either dumps the volume set specified by the +B<-volumeset> argument at the dump level specified by the B<-dump> argument +and creates a Backup Database dump record about it, or executes the +dump instructions listed in the file named by the B<-file> argument. The +Tape Coordinator indicated by the B<-portoffset> argument (or on each +command in the file) executes the operation. + +(If the B instruction appears in the +BI<_device_name> file on the Tape Coordinator machine +associated with the specified port offset, then the Backup System +dumps data to the backup data file listed for that port offset in the +Tape Coordinator's B file, rather than to +tape. For the sake of clarity, the following text refers to tapes +only, but the Backup System handles backup data files in much the same +way.) + +The term I refers to copying a collection of data to tape or a +backup data file, and the resulting collection is termed a I. The +set of tapes that contain one or more dumps is called a I. The +first dump in a dump set is its I, and any dumps +subsequently added to the dump set (by use of the B<-append> argument) +are I. Creating appended dumps is optional, and appended +dumps can be of different volume sets, and at different dump levels, +than the initial dump. + +A I, created at a full dump level in the dump hierarchy, +contains all of the data that existed at the time of the dump in the +volumes belonging to the volume set. An I, created at +an incremental dump level, contains only data that has changed since +the volume set was dumped at the incremental level's I +(the dump level immediately above the incremental level in the +hierarchy), which can be a full or incremental level. More +specifically, an incremental dump includes only the files and +directories that have modification timestamps later than the I of the volume included at the parent dump level. For backup and +read-only volumes, the clone date is the time at which the volume was +cloned from its read/write source before being included in the parent +dump; for read/write volumes, it represents the time at which the +volume was locked for inclusion in the parent dump. The clone date +appears in the I field of the output from the C +command. As an example, an incremental dump at the +B level includes only files and directories that +have changed since the volume set was dumped at the B level. + +=head2 Initiating different types of dump operations + +To initiate a dump operation that is to start as soon as the relevant +Tape Coordinator is available, provide only the B<-volumeset>, B<-dump>, +B<-portoffset>, and optionally B<-append> options. To schedule a single +C command to execute in the future, also include the B<-at> +argument to specify the start time. + +To append a dump to an existing dump set, include the B<-append> flag. +The Backup System imposes the following conditions on appended dumps: + +=over + +=item * + +If writing to tape, the Tape Coordinator checks that it is the +final one in a dump set for which there are complete and valid +tape and dump records in the Backup Database. If not, it rejects +the tape and requests an acceptable one. The operator can use the +B<-dbadd> argument to the C command to insert the +necessary records into the database. + +=item * + +The most recent dump on the tape or in the backup data file must +have completed successfully. + +=item * + +The dump set must begin with an initial dump that is recorded in +the Backup Database. If there are no dumps on the tape, then the +Backup System treats the dump operation as an initial dump and +imposes the relevant requirements (for example, checks the AFS +tape name if appropriate). + +=back + +To schedule multiple dump operations, list the operations in the file +named by the B<-file> argument. Optionally include the B<-at> argument to +specify when the C command interpreter reads the file; otherwise +it reads it immediately. Do not combine the B<-file> argument with the +command's first three arguments or the B<-append> or B<-n> flags. The +commands in the file can include any of the C command's +arguments, including the B<-at> argument to schedule them to run even +later in the future. + +To generate a list of the volumes included in a dump, without actually +dumping them, combine the B<-n> flag with the options to be used on the +actual command. + +=head2 How the Backup System executes a dump operation + +Before beginning a dump operation, the Backup System verifies that +there is a Backup Database entry for the volume set, dump level, and +port offset. If the command is correctly formed and issued in +interactive mode, it is assigned a job number and added to the jobs +list. List jobs in interactive mode by using the C<(backup) jobs> +command; terminate them with the C<(backup) kill> command. + +After obtaining the list of volumes to dump from the Volume Location +(VL) Server, the Backup System sorts the list by site (server and +partition). It groups volumes from the same site together in the dump +to minimize the number of times the operator must change tapes during +restore operations. + +The dependence of an incremental dump on its parent means that a valid +parent dump must already exist for the Backup System to create its +child incremental dump. If the Backup System does not find a record of +a dump created at the immediate parent dump level, it looks in the +Backup Database for a dump created at one level higher in the +hierarchy, and so on, up to the full dump level if necessary. It +creates an incremental dump at the level one below the lowest valid +parent dump set that it finds. If it fails to find even a full dump, +it dumps the volume set at the full dump level. + +If the Backup System is unable to access a volume during a dump +operation, it skips the volume and dumps the remaining volumes from +the volume set. Possible reasons a volume is inaccessible include +server machine or process outages, or that the volume was moved +between the time the Volume Location (VL) Server generated the list of +sites for the volume in the volume set and the time the Backup System +actually attempts to dump the data in it. After the first dumping +pass, the Backup System attempts to dump each volume it skipped. If it +still cannot dump a volume and the B instruction does not appear +in the BI<_device_name> file, it queries the operator as to whether it +needs to attempt to dump the volume again, omit the volume from the +dump, or halt the dump operation altogether. When prompted, the +operator can attempt to solve whatever problem prevented the Backup +System from accessing the volumes. If the B instruction appears +in the BI<_device_name> file, the Backup System omits the volume from +the dump. + +Before scheduling a dump operation, the Backup System verifies that +the date specified by the B<-at> argument is in the future, and checks +the validity of the volume set, dump level and port offset as for a +regular dump operation. It checks the validity of the parameters again +just before actually running the scheduled operation. + +Before writing an initial dump to a tape that does not have a +permanent name on the label, the Backup System checks that the AFS +tape name on the label is acceptable. If desired, disable name +checking by including the B instruction in the +BI<_device_name> file. + +If AFS tape name checking is enabled, the Backup System accepts the +following three types of values for the AFS tape name. If the name on +the label does not conform, the Backup System obtains a tape with an +acceptable label by invoking the B instruction in the +BI<_device_name> file or prompting the operator. + +=over + +=item 1. + +A name of the form I.I.I, +where I matches the value of the B<-volumeset> +argument, I matches the last element in the pathname +value of the B<-dump> argument, and I reflects the tape's +place in a multitape dump set. As an example, the first tape in a +dump set for which the initial dump is of volume set user at the +dump level B has AFS tape name B. If the +label records this type of AFS tape name, the Backup System +retains the AFS tape name and writes the dump to the tape. + +=item 2. + +The string CNULLE>, which usually indicates that a backup operator +has used the C command to write a label on the +tape, but did not include the B<-name> argument to assign an AFS tape +name. Presumably, the operator did include the B<-pname> argument to +assign a permanent name. If the label records a CNULLE> value, the +Backup System constructs and records on the label the appropriate +AFS tape name, and writes the dump on the tape. + +=item 3. + +No value at all, because the tape has never been labeled or used +in the Backup System. As when the AFS tape name is CNULLE>, the +Backup System constructs and records on the label the appropriate +AFS tape name, and writes the dump on the tape. + +=back + +To determine how much data it can write to a tape, the Tape +Coordinator reads the capacity recorded on the tape's label (placed +there by including the B<-size> argument to the C command). +If the label's capacity field is empty, the Tape Coordinator +uses the capacity recorded for the specified port offset in the local +B file. If the capacity field in the B file is also +empty, the Tape Coordinator uses the maximum capacity of 2 TB. + +During a dump operation, the Tape Coordinator tracks how much data it +has written and stops shortly before it reaches what it believes is +the tape's capacity. If it is in the middle of writing the data for a +volume when it reaches that point, it writes a special marker that +indicates an interrupted volume and continues writing the volume on +the next tape. It can split a volume this way during both an initial +and an appended dump, and the fact that the volume resides on multiple +tapes is automatically recorded in the Backup Database. + +If the tape is actually larger than the expected capacity, then the +Tape Coordinator simply does not use the excess tape. If the tape is +smaller than the expected capacity, the Tape Coordinator can reach the +end-of-tape (EOT) unexpectedly while it is writing data. If the Tape +Coordinator is in the middle of the writing data from a volume, it +obtains a new tape and rewrites the entire contents of the interrupted +volume to it. The data from the volume that was written to the +previous tape remains there, but is never used. + +The Backup System allows recycling of tapes (writing a new dump set +over an old dump set that is no longer needed), but imposes the +following conditions: + +=over + +=item * + +All dumps in the old dump set must be expired. The Backup System +always checks expiration dates, even when name checking is +disabled. + +=item * + +If the tape to be recycled does not have a permanent name and name +checking is enabled, then the AFS tape name derived from the new +initial dump's volume set name and dump level name must match the +AFS tape name already recorded on the label. + +=item * + +The tape cannot already have data on it that belongs to the dump +currently being performed, because that implies that the operator +or automated tape device has not removed the previous tape from +the drive, or has mistakenly reinserted it. The Tape Coordinator +generates the following message and attempts to obtain another +tape: + + Can't overwrite tape containing the dump in progress + +=item * + +The tape cannot contain data from a parent dump of the current +(incremental) dump, because overwriting a parent dump makes it +impossible to restore data from the current dump. The Tape +Coordinator generates the following message and attempts to obtain +another tape: + + Can't overwrite the parent dump parent_name (parent_dump_ID) + +=back + +To recycle a tape before all dumps on it have expired or if the AFS +tape name is wrong, use the C command to overwrite the +tape's label and remove all associated tape and dump records from the +Backup Database. + +The Tape Coordinator's default response to this command is to access +the first tape by invoking the B instruction in the +BI<_device_name> file, or by prompting the backup operator to insert +the tape if there is no B instruction. However, if the B instruction appears in the BI<_device_name> file, or if the issuer +of the butc command included the B<-noautoquery> flag, the Tape +Coordinator instead expects the tape to be in the device already. If +it is not, the Tape Coordinator invokes the B instruction or +prompts the operator. It also invokes the B instruction or prompts +for any additional tapes needed to complete the dump operation; the +issuer must arrange to provide them. + +=head1 OPTIONS + +=over 4 + +=item B<-volumeset> I + +Names the volume set to dump. The B<-dump> argument must be +provided along with this one; do not combine them with the +B<-file> argument. If using a temporary volume set, the C +command must be issued within the interactive session in which +the C command was issued with the B<-temporary> +flag. + +=item B<-dump> I + +Specifies the complete pathname of the dump level at which to +dump the volume set. The B<-volumeset> argument must be provided +along with this one; do not combine them with the B<-file> +argument. + +=item B<-portoffset> I + +Specifies the port offset number of the Tape Coordinator +handling the tapes for this operation. It must be provided +unless the default value of 0 (zero) is appropriate; do not +combine it with the B<-file> argument. + +=item B<-at> I ... + +Specifies the date and time in the future at which to run the +command, or to read the file named by the B<-file> argument. +Provide a value in the format I/I
/I [I:I], where the +month (I), day (I
), and year (I) are required. Valid +values for the year range from B<1970> to B<2037>; higher values are +not valid because the latest possible date in the standard UNIX +representation is in February 2038. The Backup System +automatically reduces any later date to the maximum value. + +The hour and minutes (I:I) are optional, but if provided must +be in 24-hour format (for example, the value B<14:36> represents +2:36 p.m.). If omitted, the time defaults to midnight (00:00 +hours). + +As an example, the value B<04/23/1999 20:20> schedules the command +for 8:20 p.m. on 23 April 1999. + +=over + +=item B + +A ... follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition. + +=back + +=item B<-append> + +Appends the dump onto the end of a tape that already contains +data from another dump. However, if the tape is not in fact +part of an existing dump set, the Backup System creates a new +dump set using the parameters of this dump. If the tape is not +the last tape in the dump set, the Tape Coordinator prompts for +insertion of the appropriate tape. Do not combine this argument +with the B<-file> argument. + +=item B<-n> + +Displays the names of volumes to be included in the indicated +dump, without actually performing the dump operation. Do not +combine this argument with the B<-file> argument. + +=item B<-file> I + +Specifies the local disk or AFS pathname of a file containing +C commands. The Backup System reads the file immediately, +or at the time specified by the B<-at> argument if it is provided. +A partial pathname is interpreted relative to the current +working directory. + +Place each C command on its own line in the indicated +file, using the same syntax as for the command line, but +without the word B at the start of the line. Each command +must include a value for the B<-volumeset> and B<-dump> arguments, +and for the B<-portoffset> argument unless the default value of 0 +is appropriate. Commands in the file can also include any of +the C command's optional options. In the following +example file, the first command runs as soon as the Backup +System reads the file, whereas the other commands are +themselves scheduled; the specified date and time must be later +than the date and time at which the Backup System reads the +file. + + dump user /sunday1/wednesday -port 1 + dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999 + dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append + +Do not combine this argument with the B<-volumeset>, B<-dump>, +B<-portoffset>, B<-append>, or B<-n> options. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The command interpreter first generates a list of the volumes to be +included in the dump by matching the entries in the volume set against +the volumes listed in the Volume Location Database (VLDB). It prints +the list following the header: + + Preparing to dump the following volumes: + +The following message then indicates that the command interpreter has +passed the dump request to the appropriate Tape Coordinator for +processing: + + Starting dump. + +If the issuer includes the B<-n> flag, the output is of the following +form: + + Starting dump of volume set 'volume set' (dump set 'dump level') + Total number of volumes : number dumped + Would have dumped the following volumes: + list_of_volumes + +where list_of_volumes identifies each volume by name and volume ID +number. + +If the Tape Coordinator is unable to access a volume, it prints an +error message in its window and records the error in its log and error +files. + +=head1 EXAMPLES + +The following command dumps the volumes in the volume set called user +at the dump level B. The issuer places the +necessary tapes in the device with port offset 5. + + backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5 + Preparing to dump the following volumes: + user.jones.backup 387623900 + user.pat.backup 486219245 + user.smith.backup 597315841 + . . + . . + Starting dump. + +The following command displays the list of volumes to be dumped when +the user dumps the B volume set at the B dump level. + + backup dump -volumeset sys_sun -dump /full -n + Starting dump of volume set 'sys_sun' (dump set '/full') + Total number of volumes: 24 + Would have dumped the following volumes: + sun4x_56 124857238 + sun4x_56.bin 124857241 + . . + . . + sun4x_55 124857997 + . . + . . + +The following command schedules a dump of the volumes in the volume +set B at the dump level B for 11:00 p.m. on 14 June +1999. The appropriate Tape Coordinator has port offset 0 (zero), so +that argument is omitted. + + backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server or Volume Location (VL) Server is +running, and on every file server machine that houses an affected +volume. If the B<-localauth> flag is included, the issuer must instead be +logged on to a server machine as the local superuser B. + +=head1 CAVEATS + +If a dump operation is interrupted or fails for any reason, data from +all volumes written to tape before the interrupt are valid can be used +in a restore operation. The Backup Database includes an entry for the +failed dump and for each volume that was successfully dumped. See the +IBM AFS Administration Guide for information on dealing with +interrupted dumps. + +If dumping to tape rather than a backup data file, it is best to use +only compatible tape devices (ones that can read the same type of +tape). Using compatible devices greatly simplifies restore operations. +The B<-portoffset> argument to the C and C commands accepts multiple port offset numbers, but the +Backup System uses the first listed port offset when restoring all +full dumps, the second port offset when restoring all level 1 dumps, +and so on. At the very least, use compatible tape devices to perform +dumps at each level. If compatible tape devices are not used, the +C command must be used to restore one volume at a +time. + +Valid (unexpired) administrative tokens must be available to the +C command interpreter both when it reads the file named by the +B<-file> argument and when it runs each operation listed in the file. +Presumably, the issuer is scheduling dumps for times when no human +operator is present, and so must arrange for valid tokens to be +available on the local machine. One option is to issue all commands +(or run all scripts) on file server machines and use the B<-localauth> +flag on the C and C commands. To protect against improper +access to the machine or the tokens, the machine must be physically +secure (perhaps even more protected than a Tape Coordinator machine +monitored by a human operator during operation). Also, if an +unattended dump requires multiple tapes, the operator must properly +configure a tape stacker or jukebox and the device configuration file. + +When the command is issued in regular (non-interactive) mode, the +command shell prompt does not return until the dump operation +completes. To avoid having to open additional connections, issue the +command in interactive mode, especially when including the B<-at> +argument to schedule dump operations. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_dumpinfo.pod b/doc/man-pages/pod/backup_dumpinfo.pod new file mode 100644 index 0000000000..53420d1ace --- /dev/null +++ b/doc/man-pages/pod/backup_dumpinfo.pod @@ -0,0 +1,427 @@ +=head1 NAME + +backup dumpinfo - Displays a dump record from the Backup Database + +=head1 SYNOPSIS + +backup dumpinfo [B<-ndumps> I] [B<-id> I] +[B<-verbose>] [B<-localauth>] [B<-cell> I] [B<-help> ] + +backup dumpi [B<-n> I] [B<-i> I] +[B<-v>] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command formats and displays the Backup Database +record for the specified dumps. To specify how many of the most recent +dumps to display, starting with the newest one and going back in time, +use the B<-ndumps> argument. To display more detailed information about a +single dump, use the B<-id> argument. To display the records for the 10 +most recent dumps, omit both the B<-ndumps> and B<-id> arguments. + +The B<-verbose> flag produces very detailed information that is useful +mostly for debugging purposes. It can be combined only with the B<-id> +argument. + +=head1 OPTIONS + +=over 4 + +=item B<-ndumps> I + +Displays the Backup Database record for each of the specified +number of dumps that were most recently performed. If the +database contains fewer dumps than are requested, the output +includes the records for all existing dumps. Do not combine +this argument with the B<-id> or B<-verbose> options; omit all +options to display the records for the last 10 dumps. + +=item B<-id> I + +Specifies the dump ID number of a single dump for which to +display the Backup Database record. Precede the I value +with the B<-id> switch; otherwise, the command interpreter +interprets it as the value of the B<-ndumps> argument. Combine +this argument with the B<-verbose> flag, but not with the B<-ndumps> +argument; omit all options to display the records for the last +10 dumps. + +=item B<-verbose> + +Provides more detailed information about the dump specified +with the B<-id> argument, which must be provided along with it. Do +not combine this flag with the B<-ndumps> argument. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the B<-ndumps> argument is provided, the output presents the following +information in table form, with a separate line for each dump: + +=over + +=item B + +The dump ID number. + +=item B + +The dump ID number of the dump's parent dump. A value of 0 +(zero) identifies a full dump. + +=item B + +The depth in the dump hierarchy of the dump level used to +create the dump. A value of 0 (zero) identifies a full dump, in +which case the value in the C field is also 0. A value +of 1 or greater indicates an incremental dump made at the +corresponding level in the dump hierarchy. + +=item B + +The date and time at which the Backup System started the dump +operation that created the dump. + +=item B + +The number of tapes that contain the data in the dump. A value +of 0 (zero) indicates that the dump operation was terminated or +failed. Use the C command to remove such +entries. + +=item B + +The number of volumes from which the dump includes data. If a +volume spans tapes, it is counted twice. A value of 0 (zero) +indicates that the dump operation was terminated or failed; the +value in the nt field is also 0 in this case. + +=item B + +The dump name in the form + +I.I (I) + +where I is the name of the volume set, and +I is the last element in the dump level pathname +at which the volume set was dumped. + +The I, if displayed, is the dump ID of the +initial dump in the dump set to which this dump belongs. If +there is no value in parentheses, the dump is the initial dump +in a dump set that has no appended dumps. + +=back + +If the B<-id> argument is provided alone, the first line of output begins +with the string C and reports information for the entire dump in +the following fields: + +=over + +=item B + +The dump ID number. + +=item B + +The depth in the dump hierarchy of the dump level used to +create the dump. A value of 0 (zero) identifies a full dump. A +value of 1 (one) or greater indicates an incremental dump made +at the specified level in the dump hierarchy. + +=item B + +The number of volumes for which the dump includes data. + +=item B + +The date and time at which the dump operation began. + +=back + +If an XBSA server was the backup medium for the dump (rather than a +tape device or backup data file), the following line appears next: + +Backup Service: I: Server: I + +where I is the name of the XBSA-compliant program and +I is the name of the machine on which the program runs. + +Next the output includes an entry for each tape that houses volume +data from the dump. Following the string C, the first two lines of +each entry report information about that tape in the following fields: + +=over + +=item B + +The tape's permanent name if it has one, or its AFS tape name +otherwise, and its tape ID number in parentheses. + +=item B + +The number of volumes for which this tape includes dump data. + +=item B + +The date and time at which the Tape Coordinator began writing +data to this tape. + +=back + +Following another blank line, the tape-specific information concludes +with a table that includes a line for each volume dump on the tape. +The information appears in columns with the following headings: + +=over + +=item B + +The relative position of each volume in this tape or file. On a +tape, the counter begins at position 2 (the tape label occupies +position 1), and increments by one for each volume. For volumes +in a backup data file, the position numbers start with 1 and do +not usually increment only by one, because each is the ordinal +of the 16 KB offset in the file at which the volume's data +begins. The difference between the position numbers therefore +indicates how many 16 KB blocks each volume's data occupies. +For example, if the second volume is at position 5 and the +third volume in the list is at position 9, that means that the +dump of the second volume occupies 64 KB (four 16-KB blocks) of +space in the file. + +=item B + +For a backup or read-only volume, the time at which it was +cloned from its read/write source. For a Read/Write volume, it +is the same as the dump creation date reported on the first +line of the output. + +=item B + +The number of bytes of data in the dump of the volume. + +=item B + +The volume name, complete with C<.backup> or C<.readonly> extension +if appropriate. + +=back + +If both the B<-id> and B<-verbose> options are provided, the output is +divided into several sections: + +=over + +=item * + +The first section, headed by the underlined string C, includes +information about the entire dump. The fields labeled C, C, +C, and C report the same values (though in a +different order) as appear on the first line of output when the +B<-id> argument is provided by itself. Other fields of potential +interest to the backup operator are: + +=over + +=item B + +The dump's I, which is recorded in the +dump's Backup Database record if the B instruction +appears in the Tape Coordinator's +BI file when the dump is created. + +=item B + +The number of tapes that contain the dump set to which +this dump belongs. + +=item B + +The ordinal of the tape on which this dump begins in the +set of tapes that contain the dump set. + +=back + +=item * + +For each tape that contains data from this dump, there follows a +section headed by the underlined string C. The fields labeled +C, C, and C report the same values (though in a +different order) as appear on the second and third lines of output +when the B<-id> argument is provided by itself. Other fields of +potential interest to the backup operator are: + +=over + +=item B + +The date and time when this tape can be recycled, because +all dumps it contains have expired. + +=item B + +Summed together, these fields represent the total amount +of dumped data actually from volumes (as opposed to +labels, filemarks, and other markers). + +=item B + +The number of kilobytes of tape (or disk space, for a +backup data file) used to store the dump data. It is +generally larger than the sum of the values in the +C Data and C Data fields, because it includes +the space required for the label, file marks and other +markers, and because the Backup System writes data at 16 +KB offsets, even if the data in a given block doesn't +fill the entire 16 KB. + +=back + +=item * + +For each volume on a given tape, there follows a section headed by +the underlined string C. The fields labeled C, C, +C, and C report the same values (though in a different +order) as appear in the table that lists the volumes in each tape +when the B<-id> argument is provided by itself. Other fields of +potential interest to the backup operator are: + +=over + +=item B + +The volume ID. + +=item B + +The name of the tape containing this volume data. + +=back + +=back + +=head1 EXAMPLES + +The following example displays information about the last five dumps: + + backup dumpinfo -ndumps 5 + dumpid parentid lv created nt nvols dump name + 924424000 0 0 04/18/1999 04:26 1 22 usr.sun (924424000) + 924685000 924424000 1 04/21/1999 04:56 1 62 usr.wed (924424000) + 924773000 924424000 1 04/22/1999 05:23 1 46 usr.thu (924424000) + 924860000 924424000 1 04/23/1999 05:33 1 58 usr.fri (924424000) + 925033000 0 0 04/25/1999 05:36 2 73 sys.week + +The following example displays a more detailed record for a single +dump. + + backup dumpinfo -id 922097346 + Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999 + Tape: name monday.user.backup (922097346) + nVolumes 1, created 03/22/1999 05:09 + Pos Clone time Nbytes Volume + 1 03/22/1999 04:43 27787914 user.pat.backup + +The following example displays even more detailed information about +the dump displayed in the previous example (dump ID 922097346). This +example includes only one exemplar of each type of section (C, +C, and C): + + backup dumpinfo -id 922097346 -verbose + Dump + ---- + id = 922097346 + Initial id = 0 + Appended id = 922099568 + parent = 0 + level = 0 + flags = 0x0 + volumeSet = user + dump path = /monday1 + name = user.monday1 + created = Mon Mar 22 05:09:06 1999 + nVolumes = 1 + id = 0 + tapeServer = + format= user.monday1.%d + maxTapes = 1 + Start Tape Seq = 1 + name = pat + instance = + cell = + Tape + ---- + tape name = monday.user.backup + AFS tape name = user.monday1.1 + flags = 0x20 + written = Mon Mar 22 05:09:06 1999 + expires = NEVER + kBytes Tape Used = 121 + nMBytes Data = 0 + nBytes Data = 19092 + nFiles = 0 + nVolumes = 1 + seq = 1 + tapeid = 0 + useCount = 1 + dump = 922097346 + Volume + ------ + name = user.pat.backup + flags = 0x18 + id = 536871640 + server = + partition = 0 + nFrags = 1 + position = 2 + clone = Mon Mar 22 04:43:06 1999 + startByte = 0 + nBytes = 19092 + seq = 0 + dump = 922097346 + tape = user.monday1.1 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_help.pod b/doc/man-pages/pod/backup_help.pod new file mode 100644 index 0000000000..72858bbed2 --- /dev/null +++ b/doc/man-pages/pod/backup_help.pod @@ -0,0 +1,95 @@ +=head1 NAME + +backup help - Displays the syntax of specified C commands or lists functional +descriptions of all C commands + +=head1 SYNOPSIS + +backup help [B<-topic> I [I ...]] [B<-help>] + +backup h [B<-t> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the complete online help entry (short +description and syntax statement) for each operation code specified by +the B<-topic> argument. If the B<-topic> argument is omitted, the output +includes the first line (name and short description) of the online +help entry for every C command. + +To list every C command whose name or short description includes +a specified keyword, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I [I ...] + +Indicates each command for which to display the complete online +help entry. Omit the C part of the command name, providing +only the operation code (for example, specify C, not C). If this argument is omitted, the output briefly +describes every C command. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The online help entry for each C command consists of the +following two or three lines: + +=over + +=item * + +The first line names the command and briefly describes its +function. + +=item * + +The second line lists aliases for the command, if any. + +=item * + +The final line, which begins with the string C, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in +this document. + +=back + +=head1 EXAMPLES + +The following example displays the online help entry for the C command: + + backup help dump + backup dump: start dump + Usage: backup dump -volumeset -dump + [-portoffset ] [-at +] + [-append] [-n] [-file ] [-help] + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_interactive.pod b/doc/man-pages/pod/backup_interactive.pod new file mode 100644 index 0000000000..e6e5b48ee5 --- /dev/null +++ b/doc/man-pages/pod/backup_interactive.pod @@ -0,0 +1,121 @@ +=head1 NAME + +backup interactive - Enters interactive mode + +=head1 SYNOPSIS + +backup [interactive] [B<-localauth>] [B<-cell> I] [B<-help>] + +backup [i] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C initiates an interactive session for issuing +C commands. As indicated in the syntax statement, the operation +code (C) is optional. + +Several features of interactive mode distinguish it from regular mode: + +=over + +=item * + +In interactive mode, the C> prompt replaces the system +(shell) prompt. The operator enters only a command's operation +code (omitting the command suite name, C). + +=item * + +If the B<-localauth> flag or the B<-cell> argument is included on the +C command, the settings apply to all commands +issued during that interactive session. The issuer does not need +to type them on every command. Another consequence is that the +flag and argument do not appear in the syntax statement generated +by the C subcommand or B<-help> flag on an individual command +issued at the C> prompt. + +=item * + +The C<(backup) jobs> and C<(backup) kill> commands are available only in +interactive mode. It is not possible to track and terminate backup +operations as cleanly in non-interactive mode. + +=item * + +It is not necessary to enclose strings that include metacharacters +in double quotes or other delimiters. + +=item * + +The C command interpreter establishes a connection to the +Backup Server, Volume Server and Volume Location (VL) Server +processes as it enters interactive mode, and uses the same +connection for all commands during the session. Execution time can +therefore be faster than in non-interactive mode, in which the +command interpreter must establish a new connection for each +command. + +=back + +To exit an interactive session, issue the C<(backup) quit> command. + +=head1 OPTIONS + +=over 4 + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example shows how the B<-localauth> flag and B<-cell> argument +do not appear when the C subcommand is issued in interactive +mode. + + backup + backup> help dump + dump: start dump + Usage: dump [-volumeset ] [-dump ] + [-portoffset ] [-at +] + [-append ] [-n ] [-file ] [-help ] + +=head1 PRIVILEGE REQUIRED + +None. However, C commands that require privilege in regular mode +still require it in interactive mode. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_jobs.pod b/doc/man-pages/pod/backup_jobs.pod new file mode 100644 index 0000000000..4068393f62 --- /dev/null +++ b/doc/man-pages/pod/backup_jobs.pod @@ -0,0 +1,229 @@ +=head1 NAME + +backup jobs - Lists pending and running operations in interactive mode + +=head1 SYNOPSIS + +jobs [B<-help>] + +j [B<-h>] + +=head1 DESCRIPTION + +The C<(backup) jobs> command lists the job ID number and status of each +B operation running or pending in the current interactive +session. + +This command can be issued in interactive mode only. If the issuer of +the C command included the B<-localauth> flag, the +B<-cell> argument, or both, those settings apply to this command also. + +To terminate operations that appear in the output, issue the C<(backup) +kill> command and identify the operation to cancel with the job ID +number from this command's output. + +To check the status of a Tape Coordinator, rather than of a certain +operation, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output always includes the expiration date and time of the tokens +that the C command interpreter is using during the current +interactive session, in the following format: + +I I
/I [I:I]. The month +(I), day (I
), and year (I) are required, and valid +values for the year range from B<1970> to B<2037>; higher values +are not valid because the latest possible date in the +standard UNIX representation is in February 2038. The Backup +System automatically reduces any later date to the maximum +value. + +The hour and minutes (I:I) are optional, but if provided +must be in 24-hour format (for example, the value B<14:36> +represents 2:36 p.m.). If omitted, the time defaults to 59 +seconds after midnight (00:00:59 hours). Similarly, the +C command interpreter automatically adds 59 seconds to +any time value provided. In both cases, adding 59 seconds +compensates for how the Backup Database and C +command represent dump creation times in hours and minutes +only. That is, the Database records a creation timestamp of +C<20:55> for any dump created between 20:55:00 and 20:55:59. +Automatically adding 59 seconds to a time thus includes the +records for all dumps created during that minute. + +=back + +=over + +=item B + +A ... follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition. + +=back + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example writes a copy of the Backup Database to the tape +device controlled by the Tape Coordinator with port offset 1: + + backup savedb -portoffset 1 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_scantape.pod b/doc/man-pages/pod/backup_scantape.pod new file mode 100644 index 0000000000..7d42072ae6 --- /dev/null +++ b/doc/man-pages/pod/backup_scantape.pod @@ -0,0 +1,359 @@ +=head1 NAME + +backup scantape - Extracts dump information from a tape + +=head1 SYNOPSIS + +backup scantape [B<-dbadd>] [B<-portoffset> I] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup sc [B<-d>] [B<-p> I] [B<-l>] [B<-c> I] [B<-help>] + +=head1 DESCRIPTION + +The C command extracts information from the dump labels +and volume headers on the tape in the device controlled by the Tape +Coordinator indicated by the B<-portoffset> argument. The Tape +Coordinator displays the information for each volume in its window as +soon as it extracts it (rather than waiting until it has scanned the +entire tape). + +(If the B instruction appears in the +BI file associated with the specified +port offset, then the C command extracts dump +information from the backup data file named in that port offset's +entry in the B file on the Tape Coordinator +machine, rather than from a tape. For the sake of clarity, the +following text refers to tapes only, but the Backup System handles +backup data files in much the same way.) + +If the B<-dbadd> flag is provided, the C command creates +new dump and volume records in the Backup Database for the scanned +information. However, if it finds that a record already exists in the +database for the same dump, it terminates the scanning operation. + +The scanning operation works only on tapes containing volume data. The +command fails with an error message if the tape contains a copy of the +Backup Database (was created with the C command, or has +the AFS tape name B). + +The Tape Coordinator's default response to this command is to access +the tape by invoking the B instruction in the BI +file, or by prompting the backup operator to insert the tape if there +is no B instruction. However, if the B instruction +appears in the BI file, or if the issuer of the B +command included the B<-noautoquery> flag, the Tape Coordinator instead +expects the tape to be in the device already. If it is not, the Tape +Coordinator invokes the B instruction or prompts the operator. + +To terminate a tape scanning operation in interactive mode, issue the +C<(backup) kill> command. In noninteractive mode, the only choice is to +use a termination signal such as > to halt the Tape Coordinator +completely. + +=head1 OPTIONS + +=over 4 + +=item B<-dbadd> + +Adds the information extracted from the tape to the Backup +Database (but only if the database does not already contain an +entry with the same dump ID number). + +=item B<-portoffset> I + +Specifies the port offset number of the Tape Coordinator +handling the tapes for this operation. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +For every dump on a tape, the C command displays in the +Tape Coordinator window the dump label and the volume header of each +volume in the dump. If a dump spans more than one tape, the dump label +does not repeat at the beginning of subsequent tapes. + +A dump label contains the following fields, which are the same as in +the output from the C command: + +=over + +=item B + +The permanent name assigned by using the B<-pname> argument of the +C command. This name remains on the tape until +that argument is used again, no matter how many times the tape +is recycled or otherwise relabeled. If the tape does not have a +permanent name, the value CNULLE> appears in this field. + +=item B + +A tape name in one of the following prescribed formats. The +Backup System automatically writes the appropriate AFS tape +name to the label as part of a C operation, or the +operator can assign it with the B<-name> argument to the C command. + +=over + +=item * + +I.I.I, if the tape +contains volume data. The I is the name of the +volume set that was dumped to create the initial dump in the +dump set of which this tape is a part; I is the +last pathname element of the dump level at which the initial +dump was backed up; and I is the numerical position +of the tape in the dump set. + +=item * + +CNULLE> if the tape has no AFS tape name. This is normally the +case if the B<-name> argument was not included the last time the +C command was used on this tape, and no data +has been written to it since. + +=back + +=item B + +The date and time at which the Backup System started performing +the dump operation that created the initial dump. + +=item B + +The cell in which the dump set was created. This is the cell +whose Backup Database contains a record of the dump set. + +=item B + +The tape's capacity (in kilobytes) as recorded on the label, +rather than the amount of data on the tape. The value is +assigned by the B<-size> argument to the C command +or derived from the B file on the Tape +Coordinator machine, not from a measurement of the tape. + +=item B + +The dump level of the initial dump in the dump set. + +=item B + +The dump ID number of the initial dump in the dump set, as +recorded in the Backup Database. + +=item B + +The number of times a dump has been written to the tape, or it +has been relabeled. + +=back + +The volume header contains the following fields: + +=over + +=item B + +The volume name, complete with a C<.backup> or C<.readonly> +extension, if appropriate. + +=item B + +The volume's volume ID. + +=item B + +The dump to which the volume belongs. The dump name is of the +form I.I and matches the name +displayed in the dump label. + +=item B + +The dump ID of the dump named in the C field. + +=item B + +The depth in the dump hierarchy of the dump level used in +creating the dump. A value of 0 indicates a full dump. A value +of 1 or greater indicates an incremental dump made at the +indicated depth in the hierarchy. The value reported is for the +entire dump, not necessarily for the volume itself; for +example, it is possible for a dump performed at an incremental +level to include a full dump of an individual volume if the +volume was omitted from previous dumps. + +=item B + +The dump ID number of C's parent dump. It is 0 if the +value in the C field is 0. + +=item B + +Is always 0; it is reserved for internal use. + +=item B + +The date and time at which the volume was created. For a backup +or read-only volume, this represents the time at which it was +cloned from its read/write source. For a read/write volume, it +indicates the time at which the Backup System locked the volume +for purposes of including it in the dump named in the +C field. + +=back + +The message C indicates the completion of the output. + +In normal circumstances, the Backup System writes a marker to indicate +that a volume is the last one on a tape, or that the volume continues +on the next tape. However, if a backup operation terminated abnormally +(for example, because the operator terminated the Tape Coordinator by +issuing the > command during the operation), then there is no +such marker. Some very early versions of the Backup System also did +not write these markers. If a tape does not conclude with one of the +expected markers, the Tape Coordinator cannot determine if there is a +subsequent tape in the dump set and so generates the following message +in its window: + + Are there more tapes? (y/n) + +=head1 EXAMPLES + +The following example shows the output for the first two volumes on a +tape in the device with port offset 0: + + backup scantape + Dump label + ---------- + tape name = monthly_guest + AFS tape name = guests.monthly.3 + creationTime = Mon Feb 1 04:06:40 1999 + cell = abc.com + size = 2150000 Kbytes + dump path = B + dump id = 917860000 + useCount = 44 + -- End of dump label -- + -- volume -- + volume name: user.guest10.backup + volume ID 1937573829 + dumpSetName: guests.monthly + dumpID 917860000 + level 0 + parentID 0 + endTime 0 + clonedate Mon Feb 1 03:03:23 1999 + -- volume -- + volume name: user.guest11.backup + volume ID 1938519386 + dumpSetName: guests.monthly + dumpID 917860000 + level 0 + parentID 0 + endTime 0 + clonedate Mon Feb 1 03:05:15 1999 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +A scanning operation does not have to begin with the first tape in a +dump set, but the Backup System can process tapes only in sequential +order after the initial tape provided. The Tape Coordinator +automatically requests any subsequent tapes by invoking the B +instruction in the local BI file, or by +prompting the operator if there is no B instruction. + +The Tape Coordinator's success in scanning a tape that is corrupted or +damaged depends on the extent of the damage and what type of data is +corrupted. It can almost always scan the tape successfully up to the +point of damage. If the damage is minor, the Tape Coordinator can +usually skip over it and scan the rest of the tape, but more major +damage can prevent further scanning. Because a scanning operation can +start on any tape in a dump set, damage on one tape does not prevent +scanning of the others in the dump set. However, it is possible to +scan either the tapes that precede the damaged one or the ones that +follow it, but not both. + +If a tape is relabeled with the C command, it is not +possible to recover data from it for the purposes of rebuilding the +Backup Database. + +If the B<-dbadd> flag is included on the command, it is best not to +terminate the tape scanning operation before it completes (for +example, by issuing the C<(backup) kill> command in interactive mode). +The Backup System writes a new record in the Backup Database for each +dump as soon as it scans the relevant information on the tape, and so +it possibly has already written new records. If the operator wants to +rerun the scanning operation, he or she must locate and remove the +records created during the terminated operation: the second operation +exits automatically if it finds that a record that it needs to create +already exists. + +If the B<-dbadd> flag is included and the first tape provided is not the +first tape in the dump set, the following restrictions apply: + +=over + +=item * + +If the first data on the tape is a continuation of a volume that +begins on the previous (unscanned) tape in the dump set, the +Backup System does not add a record for that volume to the Backup +Database. + +=item * + +The Backup System must read the marker that indicates the start of +an appended dump to add database records for the volumes in it. If +the first volume on the tape belongs to an appended dump, but is +not immediately preceded by the appended-dump marker, the Backup +System does not create a Backup Database record for it or any +subsequent volumes that belong to that appended dump. + +=back + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_setexp.pod b/doc/man-pages/pod/backup_setexp.pod new file mode 100644 index 0000000000..4070345f95 --- /dev/null +++ b/doc/man-pages/pod/backup_setexp.pod @@ -0,0 +1,175 @@ +=head1 NAME + +backup setexp - Sets the expiration date for existing dump levels. + +=head1 SYNOPSIS + +backup setexp B<-dump> I [I ...] [B<-expires> I ...] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup se B<-d> I [I ...] [B<-e> I ...] +[B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command sets or changes the expiration date +associated with each specified dump level, which must already exist in +the dump hierarchy. + +Use the B<-expires> argument to associate an expiration date with each +dump level. When the Backup System subsequently creates a dump at the +dump level, it uses the specified value to derive the dump's +expiration date, which it records on the label of the tape (or backup +data file). The Backup System refuses to overwrite a tape until after +the latest expiration date of any dump that the tape contains, unless +the C command is used to relabel the tape. If a dump +level does not have an expiration date, the Backup System treats dumps +created at the level as expired as soon as it creates them. + +(Note that the Backup System does not automatically remove a dump's +record from the Backup Database when the dump reaches its expiration +date, but only if the tape that contains the dump is recycled or +relabeled. To remove expired and other obsolete dump records, use the +C command.) + +Define either an absolute or relative expiration date: + +=over + +=item * + +An absolute expiration date defines the month/day/year (and, +optionally, hour and minutes) at which a dump expires. If the +expiration date predates the dump creation time, the Backup System +immediately treats the dump as expired. + +=item * + +A relative date defines the number of years, months, or days (or a +combination of the three) after the dump's creation that it +expires. When the Backup System creates a dump at the dump level, +it calculates an actual expiration date by adding the relative +date to the start time of the dump operation. + +=back + +If the command is used to change an existing expiration date +associated with a dump level, the new date applies only to dumps +created after the change. Existing dumps retain the expiration date +assigned at the time they were created. + +=head1 OPTIONS + +=over 4 + +=item B<-dump> I [I ...] + +Specifies the full pathname of each dump level to assign the +expiration date specified by the B<-expires> argument. + +=item B<-expires> I ... + +Defines the absolute or relative expiration date to associate +with each dump level named by the B<-dump> argument. Absolute +expiration dates have the following format: + +[B] {B | I/I
/I [I:I] } + +where the optional word C is followed either by the string +C, which indicates that dumps created at the dump level +never expire, or by a date value with a required portion (I +for month, I
for day, and I for year) and an optional +portion (I for hours and I for minutes). + +Omit the I:I portion to use the default of midnight (00:00 +hours), or provide a value in 24-hour format (for example, +B<20:30> is 8:30 p.m.). Valid values for the year range from B<1970> +to B<2037>; higher values are not valid because the latest +possible date in the standard UNIX representation is in +February 2038. The command interpreter automatically reduces +later dates to the maximum value. + +Relative expiration dates have the following format: + +[B] [IB] [IB] [IB] + +where the optional word C is followed by at least one of a +number of years (maximum B<9999>) followed by the letter C, a +number of months (maximum B<12>) followed by the letter C, or a +number of days (maximum B<31>) followed by the letter C. If +providing more than one of the three, list them in the +indicated order. If the date that results from adding the +relative expiration value to a dump's creation time is later +than the latest possible date in the UNIX time representation, +the Backup System automatically reduces it to that date. + +=over + +=item B + +A ... follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition to be associated with each dump level specified by the +B<-dump> argument. + +=back + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example associates an absolute expiration date of 10:00 +p.m. on 31 December 1999 with the dump level B: + + backup setexp -dump B -expires at 12/31/1999 22:00 + +The following example associates a relative expiration date of 7 days +with the two dump levels B and B: + + backup setexp -dump B B -expires 7d + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_status.pod b/doc/man-pages/pod/backup_status.pod new file mode 100644 index 0000000000..3ce84182bc --- /dev/null +++ b/doc/man-pages/pod/backup_status.pod @@ -0,0 +1,198 @@ +=head1 NAME + +backup status - Reports a Tape Coordinator's status + +=head1 SYNOPSIS + +backup status [B<-portoffset> I] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup st [B<-p> I] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command displays which operation, if any, the +indicated Tape Coordinator is currently executing. + +=head1 OPTIONS + +=over 4 + +=item B<-portoffset> I + +Specifies the port offset number of the Tape Coordinator for +which to report the status. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The following message indicates that the Tape Coordinator is not +currently performing an operation: + +Tape coordinator is idle + +Otherwise, the output includes a message of the following format for +each running or pending operation: + +Task I: I: I + +where + +=over + +=item B> + +Is a task identification number assigned by the Tape +Coordinator. It begins with the Tape Coordinator's port offset +number. + +=item B> + +Identifies the operation the Tape Coordinator is performing, +which is initiated by the indicated command: + +=over + +=item * + +Dump (the C command) + +=item * + +Restore (the backup diskrestore, backup volrestore, or C commands) + +=item * + +Labeltape (the C command) + +=item * + +Scantape (the C command) + +=item * + +SaveDb (the C command) + +=item * + +RestoreDb (the C command) + +=back + +=item B> + +Indicates the job's current status in one of the following +messages. + +=over + +=item B Kbytes transferred, volume I> + +For a running dump operation, indicates the number of +kilobytes copied to tape or a backup data file so far, +and the volume currently being dumped. + +=item B Kbytes, restore.volume> + +For a running restore operation, indicates the number of +kilobytes copied into AFS from a tape or a backup data +file so far. + +=item B<[abort requested]> + +The C<(backup) kill> command was issued, but the termination +signal has yet to reach the Tape Coordinator. + +=item B<[abort sent]> + +The operation is canceled by the C<(backup) kill> command. +Once the Backup System removes an operation from the +queue or stops it from running, it no longer appears at +all in the output from the command. + +=item B<[butc contact lost]> + +The C command interpreter cannot reach the Tape +Coordinator. The message can mean either that the Tape +Coordinator handling the operation was terminated or +failed while the operation was running, or that the +connection to the Tape Coordinator timed out. + +=item B<[done]> + +The Tape Coordinator has finished the operation. + +=item B<[drive wait]> + +The operation is waiting for the specified tape drive to +become free. + +=item B<[operator wait]> + +The Tape Coordinator is waiting for the backup operator +to insert a tape in the drive. + +=back + +=back + +If the Tape Coordinator is communicating with an XBSA server (a +third-party backup utility that implements the Open Group's Backup +Service API [XBSA]), the following message appears last in the output: + +I Tape coordinator + +where I is the name of the XBSA-compliant program. + +=head1 EXAMPLES + +The following example shows that the Tape Coordinator with port offset +4 has so far dumped about 1.5 MB of data for the current dump +operation, and is currently dumping the volume named B: + + backup status -portoffset 4 + Task 4001: Dump: 1520 Kbytes transferred, volume user.pat.backup + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_volinfo.pod b/doc/man-pages/pod/backup_volinfo.pod new file mode 100644 index 0000000000..21b0c2ef61 --- /dev/null +++ b/doc/man-pages/pod/backup_volinfo.pod @@ -0,0 +1,134 @@ +=head1 NAME + +backup volinfo - Displays a volume's dump history from the Backup Database + +=head1 SYNOPSIS + +backup volinfo B<-volume> I +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup voli B<-v> I [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command displays a dump history of the specified +volume, reporting information such as the date on which the volume was +dumped and the tapes that contain it. Include the C<.backup> extension on +the volume name if the backup version of the volume was dumped. + +=head1 OPTIONS + +=over 4 + +=item B<-volume> I + +Names the volume for which to display the dump history. Include +the C<.backup> or C<.readonly> extension if the backup or read-only +version of the volume was dumped. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output includes a line for each Backup Database dump record that +mentions the specified volume, order from most to least recent. The +output for each record appears in a table with six columns: + +=over + +=item B + +The dump ID of the dump that includes the volume. + +=item B + +The depth in the dump hierarchy of the dump level at which the +volume was dumped. A value of 0 indicates a full dump. A value +of 1 or greater indicates an incremental dump made at the +specified depth in the dump hierarchy. + +=item B + +The dump ID of the dump's parent dump. A value of 0 indicates a +full dump, which has no parent; in this case, the value in the +C column is also 0. + +=item B + +The date and time at which the Backup System started the dump +operation that created the dump. + +=item B + +For a backup or read-only volume, the time at which it was +cloned from its read/write source. For a read/write volume, the +same as the value in the creation date field. + +=item B + +The name of the tape containing the dump: either the permanent +tape name, or an AFS tape name in the format +I.I.I where +I is the name of the volume set associated with +the initial dump in the dump set of which this tape is a part; +I is the name of the dump level at which the +initial dump was backed up; I is the ordinal of the +tape in the dump set. Either type of name can be followed by a +dump ID in parentheses; if it appears, it is the dump ID of the +initial dump in the dump set to which this appended dump +belongs. + +=back + +=head1 EXAMPLES + +The following example shows part of the dump history of the Backup +volume user.smith.backup: + + backup volinfo -volume user.smith.backup + DumpID lvl parentID creation date clone date tape name + 924600000 1 924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392) + 924514392 1 924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2 + 924427600 0 0 04/18/1999 05:26 04/18/1999 04:58 user_full_6 + . . . . . . . . + . . . . . . . . + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_volrestore.pod b/doc/man-pages/pod/backup_volrestore.pod new file mode 100644 index 0000000000..6c2aa84bae --- /dev/null +++ b/doc/man-pages/pod/backup_volrestore.pod @@ -0,0 +1,336 @@ +=head1 NAME + +backup volrestore - Restores one or more volumes + +=head1 SYNOPSIS + +backup volrestore B<-server> I +B<-partition> I +B<-volume> I [I ...] +[B<-extension> I] +[B<-date> I ...] +[B<-portoffset> I [I ...]] [B<-n>] +[B<-localauth>] [B<-cell> I] [B<-help>] + +backup volr B<-s> I B<-pa> I +B<-v> I [I ...] [B<-e> I] +[B<-d> I ...] [B<-po> I [I ...]] +[B<-n>] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command restores the contents of one or more +volumes to the site indicated by the B<-server> and B<-partition> arguments. +Use the command either to overwrite the contents of existing volumes +with the restored data or to create new volumes while retaining the +existing ones. The specified site does not have to be the current site +for the volumes. + +(If the B instruction appears in the +BI file associated with the specified +port offset, then the C command restores data from the +backup data file listed for that port offset in the Tape Coordinator's +B file, rather than from tape. For the sake +of clarity, the following text refers to tapes only, but the Backup +System handles backup data files in much the same way.) + +The command's arguments can be combined as indicated: + +=over + +=item * + +To preserve a volume's current contents and also create a new +volume to house the restored version, use the B<-extension> argument. +The Backup System creates the new volume on the server and +partition named by the B<-server> and B<-partition> arguments, assigns +it the same name as the current volume with the addition of the +specified extension, and creates a new Volume Location Database +(VLDB) entry for it. Creating a new volume enables the +administrator to compare the two versions. + +=item * + +To overwrite a volume's existing contents with the restored +version, omit the B<-extension> argument, and specify the site as +indicated: + +=over + +=item * + +To retain the current site, specify it with the B<-server> and +B<-partition> arguments. + +=item * + +To move the volume to a different site while overwriting it, +specify the new site with the B<-server> argument, B<-partition> +argument, or both. The Backup System creates a new volume at +that site, removes the existing volume, and updates the site +information in the volume's VLDB entry. The backup version of +the volume is not removed automatically from the original +site, if it exists. Use the C command to remove it +and the C command to create a backup version at the +new site. + +=back + +=item * + +To restore a volume that no longer exists in the file system, +specify its name with the B<-volume> argument and use the B<-server> and +B<-partition> arguments to place it at the desired site. The Backup +System creates a new volume and new VLDB entry. + +=back + +In each case, the command sets each volume's creation date to the date +and time at which it restores it. The creation date appears in the +Creation field in the output from the C and C +commands. + +If restoring all of the volumes that resided on a single partition, it +is usually more efficient to use the C command. If +restoring multiple volumes to many different sites, it can be more +efficient to use the C command. + +By default, the C command restores the most recent +full dump and all subsequent incremental dumps for each volume, +bringing the restored volumes to the most current possible state. To +restore the volumes to their state at some time in the past, use the +B<-date> argument. The Backup System restores the most recent full dump +and each subsequent incremental dump for which the I of the +volume included in the dump is before the indicated date and time (the +clone date timestamp appears in the C field of the output +from the C command). For backup and read-only volumes, +the clone date represents the time at which the volume was copied from +its read/write source; for read/write volumes, it represents the time +at which the volume was locked for inclusion in the dump. The +resemblance of a restored volume to its actual state at the indicated +time depends on the amount of time that elapsed between the volume's +clone date in the last eligible dump and the specified time. + +If the B<-volume> argument specifies the base (read/write) form of the +volume name, the Backup System searches the Backup Database for the +newest dump set that includes a dump of either the read/write or the +backup version of the volume. It restores the dumps of that version of +the volume, starting with the most recent full dump. If, in contrast, +the volume name explicitly includes the C<.backup> or C<.readonly> +extension, the Backup System restores dumps of the corresponding +volume version only. + +To generate a list of the tapes the Backup System needs to perform the +restore operation, without actually performing it, combine the B<-n> flag +with the options to be used on the actual command. + +If all of the full and incremental dumps of all relevant volumes were +not written to a type of tape that a single Tape Coordinator can read, +use the B<-portoffset> argument to list multiple port offset numbers in +the order in which the tapes are needed (first list the port offset +for the full dump, second the port offset for the level 1 incremental +dump, and so on). If restoring multiple volumes, the same ordered list +of port offsets must apply to all of them. If not, either issue this +command separately for each volume, or use the C +command after defining groups of volumes that were dumped to +compatible tape types. For further discussion, see the IBM AFS +Administration Guide. + +The Tape Coordinator's default response to this command is to access +the first tape it needs by invoking the B instruction in the local +BI file, or by prompting the backup +operator to insert the tape if there is no B instruction. However, +if the B instruction appears in the BI file, +or if the issuer of the B command included the B<-noautoquery> flag, +the Tape Coordinator instead expects the tape to be in the device +already. If it is not, or is the wrong tape, the Tape Coordinator +invokes the B instruction or prompts the operator. It also invokes +the B instruction or prompts for any additional tapes needed to +complete the restore operation; the backup operator must arrange to +provide them. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Names the file server machine on which to restore each volume. +If this argument and the B<-partition> argument indicate a site +other than the current site for each volume, and the B<-extension> +argument is not also provided, the Backup System removes the +existing volumes from their current sites, places the restored +contents at the specified site, and changes the site +information in the volume's VLDB entry. + +=item B<-partition> I + +Names the partition to which to restore each volume. If this +argument and the B<-server> argument indicate a site other than +the current site for each volume, and the B<-extension> argument +is not also provided, the Backup System removes the existing +volumes from their current sites, places the restored contents +at the specified site, and changes the site information in the +volume's VLDB entry. + +=item B<-volume> I [I ...] + +Names one or more volumes to restore, using the volume name as +listed in the Backup Database. Provide the base (read/write) +name of each volume to have the Backup System search the Backup +Database for the newest dump set that includes a dump of either +the read/write or the backup version of the volume; it restores +the dumps of that version of the volume, starting with the most +recent full dump. If, in contrast, a volume name explicitly +includes the C<.backup> or C<.readonly> extension, the Backup System +restores dumps of the corresponding volume version only. + +=item B<-extension> I + +Creates a new volume to house the restored data, with a name +derived by appending the specified string to each volume named +by the B<-volume> argument. The Backup System creates a new VLDB +entry for the volume. Any string other than C<.readonly> or +C<.backup> is acceptable, but the combination of the existing +volume name and extension cannot exceed 22 characters in +length. To use a period to separate the extension from the +name, specify it as the first character of the string (as in +C<.rst>, for example). + +=item B<-date> I ... + +Specifies a date and optionally time; the restored volume +includes data from dumps performed before the date only. +Provide a value in the format I/I
/I [I:I], where the +required I/I
/I portion indicates the month (I), day (I
), +and year (I), and the optional I:I portion indicates the +hour and minutes in 24-hour format (for example, the value +B<14:36> represents 2:36 p.m.). If omitted, the time defaults to +59 seconds after midnight (00:00:59 hours). + +Valid values for the year range from B<1970> to B<2037>; higher +values are not valid because the latest possible date in the +standard UNIX representation is in February 2038. The command +interpreter automatically reduces any later date to the maximum +value. + +If this argument is omitted, the Backup System restores all +possible dumps including the most recently created. + +=over + +=item B + +A plus sign follows this argument in the command's syntax +statement because it accepts a multiword value which does not need to +be enclosed in double quotes or other delimiters, not because it +accepts multiple dates. Provide only one date (and optionally, time) +definition. + +=back + +=item B<-portoffset> I [I ...] + +Specifies one or more port offset numbers (up to a maximum of +128), each corresponding to a Tape Coordinator to use in the +operation. If there is more than one value, the Backup System +uses the first one when restoring the full dump of each volume, +the second one when restoring the level 1 incremental dump of +each volume, and so on. It uses the final value in the list +when restoring dumps at the corresponding depth in the dump +hierarchy and all dumps at lower levels. + +Provide this argument unless the default value of 0 (zero) is +appropriate for all dumps. If B<0> is just one of the values in +the list, provide it explicitly in the appropriate order. + +=item B<-n> + +Displays the list of tapes that contain the dumps required by +the restore operation, without actually performing the +operation. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the issuer includes the B<-n> flag with the command, the following +string appears at the head of the list of the tapes necessary to +complete the restore operation. + +Tapes needed: + +=head1 EXAMPLES + +The following command restores the volume B to partition +B on machine B: + + backup volrestore -server fs5.abc.com -partition a -volume user.pat + +The following command restores the volumes B and B +to partition B on machine B, adding a B<.rst> extension +to each volume name and preserving the existing B and +B volumes. Only dumps created before 5:00 p.m. on 31 January +1998 are restored. (The command is shown here on multiple lines only +for legibility reasons.) + + backup volrestore -server fs4.abc.com -partition b \ + -volume user.smith user.terry \ + -extension .rst -date 1/31/1998 17:00 + +The following command restores the volume B to partition +B on machine B. The Tape Coordinator with port offset +1 handles the tape containing the full dump; the Tape Coordinator with +port offset 0 handles all tapes containing incremental dumps. (The +command is shown here on two lines only for legibility reasons.) + + backup volrestore -server fs5.abc.com -partition a \ + -volume user.pat -portoffset 1 0 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server or Volume Location (VL) Server is +running, and on every file server machine that houses an affected +volume. If the B<-localauth> flag is included, the issuer must instead be +logged on to a server machine as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/backup_volsetrestore.pod b/doc/man-pages/pod/backup_volsetrestore.pod new file mode 100644 index 0000000000..1cdb9bb8f6 --- /dev/null +++ b/doc/man-pages/pod/backup_volsetrestore.pod @@ -0,0 +1,424 @@ +=head1 NAME + +backup volsetrestore - Restores all volumes in a volume set + +=head1 SYNOPSIS + +backup volsetrestore [B<-name> I] [B<-file> I] +[B<-portoffset> I [I ...]] +[B<-extension> I] +[B<-n>] [B<-localauth>] [B<-cell> I] [B<-help>] + +backup vols [B<-na> I] [B<-f> I] +[B<-p> I [I ...]] [B<-e> I] +[B<-n>] [B<-l>] [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command restores the complete contents of a +group of read/write volumes to the file system, by restoring data from +the last full dump and all subsequent incremental dumps of each +volume. It is most useful for recovering from loss of data on multiple +partitions, since it can restore each of a defined set of volumes to a +different site. + +(If the B instruction appears in the +BI file associated with the specified +port offset, then the C command restores data from +the backup data file listed for that port offset in the Tape +Coordinator's B file, instead of from tape. +For the sake of clarity, the following text refers to tapes only, but +the Backup System handles backup data files in much the same way.) + +If restoring one or more volumes to a single site only, it is usually +more efficient to use the C command. If restoring all +volumes that resided on a single partition, it is usually more +efficient to use the C command. + +Indicate the volumes to restore by providing either the B<-name> argument +or the B<-file> argument: + +=over + +=item * + +The B<-name> argument names a volume set. The Backup System restores +all volumes listed in the Volume Location Database (VLDB) that +match the server, partition, and volume name criteria defined in +the volume set's volume entries, and for which dumps are +available. It restores the volumes to their current site (machine +and partition), and by default overwrites the existing volume +contents. + +It is not required that the volume set was previously used to back +up volumes (was used as the B<-volumeset> option to the C +command). It can be defined especially to match the volumes that +need to be restored with this command, and that is usually the +better choice. Indeed, a temporary volume set, created by +including the B<-temporary> flag to the C command, can +be especially useful in this context. A temporary volume set is +not added to the Backup Database and exists only during the +current interactive backup session, which is suitable if the +volume set is needed only to complete the single restore operation +initialized by this command. + +The reason that a specially defined volume set is probably better +is that volume sets previously defined for use in dump operations +usually match the backup version of volumes, whereas for a restore +operation it is best to define volume entries that match the base +(read/write) name. In that case, the Backup System searches the +Backup Database for the newest dump set that includes either the +read/write or the backup version of the volume. If, in contrast, a +volume entry explicitly matches the volume's backup or read-only +version, the Backup System restores dumps of that volume version +only. + +=item * + +The B<-file> argument names a file that lists specific volumes and +the site to which to restore each. The volume name must match the +name used in Backup Database dump records rather than in the VLDB, +if they differ, because the Backup System does not look up volumes +in the VLDB. The specified site can be different than the volume's +current one; in that case, the Backup System removes the current +version of the volume and updates the volume's location +information in the VLDB. + +=back + +If all of the full and incremental dumps of all relevant volumes were +not written to a type of tape that a single Tape Coordinator can read, +use the B<-portoffset> argument to list multiple port offset numbers in +the order in which the tapes are needed (first list the port offset +for the full dump, second the port offset for the level 1 incremental +dump, and so on). This implies that the full dumps of all relevant +volumes must have been written to a type of tape that the first Tape +Coordinator can read, the level 1 incremental dumps to a type of tape +the second Tape Coordinator can read, and so on. If dumps are on +multiple incompatible tape types, use the C command to +restore individual volumes, or use this command after defining new +volume sets that group together volumes that were dumped to compatible +tape types. For further discussion, see the IBM AFS Administration +Guide. + +By default, the Backup System overwrites the contents of an existing +volume with the restored data. To create a new volume to house the +restored version instead, use the B<-extension> argument. The Backup +System derives the new volume's name by adding the specified extension +to the read/write base name, and creates a new VLDB entry. The command +does not affect the existing volume in any way. However, if a volume +with the specified extension also already exists, the command +overwrites it. + +The B<-n> flag produces a list of the volumes to be restored if the B<-n> +flag were not included, without actually restoring any volumes. See +the L section of this reference page for a detailed description +of the output, and suggestions on how to combine it most effectively +with the B<-file> and B<-name> arguments. + +The execution time for a C command depends on the +number of volumes to be restored and the amount of data in them, but +it can take hours to restore a large number of volumes. One way to +reduce the time is to run multiple instances of the command +simultaneously, either using the B<-name> argument to specify disjoint +volume sets for each command, or the B<-file> argument to name files that +list different volumes. This is possible if there are multiple +available Tape Coordinators that can read the required tapes. +Depending on how the volumes to be restored were dumped to tape, +specifying disjoint volume sets can also reduce the number of tape +changes required. + +The Tape Coordinator's default response to this command is to access +the first tape it needs by invoking the B instruction in the local +BI file, or by prompting the backup +operator to insert the tape if there is no B instruction. However, +if the B instruction appears in the BI file, +or if the issuer of the B command included the B<-noautoquery> flag, +the Tape Coordinator instead expects the tape to be in the device +already. If it is not, or is the wrong tape, the Tape Coordinator +invokes the B instruction or prompts the operator. It also invokes +the B instruction or prompts for any additional tapes needed to +complete the restore operation; the backup operator must arrange to +provide them. + +=head1 OPTIONS + +=over 4 + +=item B<-name> I + +Names a volume set to restore. The Backup System restores all +of the volumes listed in the VLDB that match the volume set's +volume entries. Provide this argument or the B<-file> argument, +but not both. + +=item B<-file> I + +Specifies the full pathname of a file that lists one or more +volumes and the site (file server machine and partition) to +which to restore each. Use either this argument or the B<-name> +argument, but not both. + +Each volume's entry must appear on its own (unbroken) line in +the file, and have the following format: + + machine partition + volume [comments...] + +where + +=over + +=item B + +Names the file server machine to which to restore the +volume. + +=item B + +Names the partition to which to restore the volume. + +=item B + +Names the volume to restore. It is generally best to +specify the base (read/write) name of each volume. In +this case, the Backup System searches the Backup Database +for the newest dump set that includes a dump of either +the read/write or the backup version of the volume. It +restores the dumps of that version of the volume, +starting with the most recent full dump. If, in contrast, +the name explicitly includes the B<.backup> or B<.readonly> +extension, the Backup System restores dumps of that +volume version only. + +=item B + +Is any other text. The Backup System ignores any text on +each line that appears after the volume name, so this +field can be used for notes helpful to the backup +operator or other administrator. + +=back + +Do not use wildcards (for example, B<.*>) in the I, +I, or I fields. It is acceptable for multiple +lines in the file to name the same volume, but the Backup +System processes only the first of them. + +=item B<-extension> I + +Creates a new volume for each volume specified by the B<-name> or +B<-file> argument, to house the restored data from that volume. +The Backup System derives the new volume's name by appending +the specified string to the read/write base name, and creates a +new VLDB volume entry. It preserves the contents of each +existing volume. Any string other than B<.readonly> or B<.backup> is +acceptable, but the combination of the base name and extension +cannot exceed 22 characters in length. To use a period to +separate the extension from the name, specify it as the first +character of the string (as in B<.rst>, for example). + +=item B<-portoffset> I [I ...] + +Specifies one or more port offset numbers (up to a maximum of +128), each corresponding to a Tape Coordinator to use in the +operation. If there is more than one value, the Backup System +uses the first one when restoring the full dump of each volume, +the second one when restoring the level 1 incremental dump of +each volume, and so on. It uses the final value in the list +when restoring dumps at the corresponding depth in the dump +hierarchy and all dumps at lower levels. + +Provide this argument unless the default value of 0 (zero) is +appropriate for all dumps. If B<0> is just one of the values in +the list, provide it explicitly in the appropriate order. + +=item B<-n> + +Displays a list of the volumes to be restored if the flag were +not included, without actually restoring them. The L +section of this reference page details the format of the +output. When combined with the B<-name> argument, its output is +easily edited for use as input to the B<-file> argument on a +subsequent C command. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter +presents it to the Backup Server, Volume Server and VL Server +during mutual authentication. Do not combine this flag with the +B<-cell> argument. For more details, see the introductory L +reference page. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the B<-n> flag is not provided, the command displays a unique task ID +number for the operation, in two places: + +=over + +=item * + +In the shell window, directly following the command line + +=item * + +In the Tape Coordinator window, if the B process was started at +debug level 1 + +=back + +The task ID number is not the same as the job ID number displayed by +the C<(backup) jobs> command when the C<(backup) volsetrestore> command is +issued in interactive mode. The Backup System does not assign either +type of ID number until the restoration process actually begins. + +When the B<-n> flag is included, no task ID or job ID numbers are +reported because none are assigned. Instead, the output begins with a +count of the number of volumes to be restored, followed by a line for +each dump of a volume. For each volume, the line representing the most +recent full dump appears first, and lines for any subsequent +incremental dumps follow, ordered by dump level. The lines for a given +volume do not necessarily appear all together, however. + +The format of each line is as follows (the output is shown here on two +lines only for legibility reasons): + + machine partition volume_dumped # as volume_restored; tape_name (tape_ID); \ + pos position_number; date + +where + +=over + +=item B + +Names the file server machine that currently houses the volume, +as listed in the VLDB. + +=item B + +Names the partition that currently houses the volume, as listed +in the VLDB. + +=item B + +Specifies the version (read/write or backup) of the volume that +was dumped, as listed in the Backup Database. + +=item B + +Specifies the name under which to restore the volume. The +Backup System only restores data to read/write volumes. If the +B<-extension> argument is included, then the specified extension +appears on the name in this field (for example, C). + +=item B + +Names the tape containing the dump of the volume, from the +Backup Database. If the tape has a permanent name, it appears +here; otherwise, it is the AFS tape name. + +=item B + +The tape ID of the tape containing the dump of the volume, from +the Backup Database. + +=item B + +Specifies the dump's position on the tape (for example, C<31> +indicates that 30 volume dumps precede the current one on the +tape). If the dump was written to a backup data file, this +number is the ordinal of the 16 KB-offset at which the volume's +data begins. + +=item B + +The date and time when the volume was dumped. + +=back + +One way to generate a file for use as input to the B<-file> argument is +to combine the B<-name> and B<-n> options, directing the output to a file. +The IBM AFS Administration Guide section on using the Backup System to +restore data explains how to edit the file as necessary before using +it as input to the B<-file> argument. + +The output of this command includes only volumes for which the Backup +Database includes at least one dump record. The command interpreter +generates a message on the standard error stream about volumes that do +not have dump records but either are listed in the file named by the +B<-file> argument, or appear in the VLDB as a match to a volume entry in +the volume set named by the B<-name> argument. + +=head1 EXAMPLES + +The following command restores all volumes included in entries in the +volume set named B, which was created expressly to restore +data to a pair of file server machines on which all data was corrupted +due to a software error. All volumes are restored to the sites +recorded in their entries in the VLDB. + + backup volsetrestore -name data.restore + Starting restore + backup: task ID of restore operation: 112 + backup: Finished doing restore + +The following command restores all volumes that have entries in the +file named B: + + backup volsetrestore -file B + Starting restore + backup: task ID of restore operation: 113 + backup: Finished doing restore + +The B file has the following contents: + + fs1.abc.com b user.pat + fs1.abc.com b user.terry + fs1.abc.com b user.smith + fs2.abc.com c user.jones + . . . + . . . + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server or Volume Location (VL) Server is +running, and on every file server machine that houses an affected +volume. If the B<-localauth> flag is included, the issuer must instead be +logged on to a server machine as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos.pod b/doc/man-pages/pod/bos.pod new file mode 100644 index 0000000000..c34c8a3fe6 --- /dev/null +++ b/doc/man-pages/pod/bos.pod @@ -0,0 +1,299 @@ +=head1 NAME + +bos - Introduction to the C command suite + +=head1 DESCRIPTION + +The commands in the C command suite are the administrative interface +to the Basic OverSeer (BOS) Server, which runs on every file server +machine to monitor the other server processes on it. If a process +fails, the BOS Server can restart it automatically, taking into +account interdependencies between it and other processes. The BOS +Server frees system administrators from constantly monitoring the +status of server machines and processes. + +There are several categories of commands in the C command suite: + +=over + +=item * + +Commands to administer server process binary files: C, +C, C, and C + +=item * + +Commands to maintain system configuration files: C, C, C, C, C, C, +C, C, C, and C + +=item * + +Commands to start and stop processes: C, C, C, C, C, C, and C + +=item * + +Commands to set and verify server process and server machine +status: C, C, C, C, +and C + +=item * + +A command to restore file system consistency: C + +=item * + +Commands to obtain help: C and C + +=back + +The BOS Server and the C commands use and maintain the following +configuration and log files: + +=over + +=item * + +The B file lists the local cell's database +server machines. These machines run the Authentication, Backup, +Protection and Volume Location (VL) Server processes, which +maintain databases of administrative information. The database +server processes consult the file to learn about their peers, +whereas the other server processes consult it to learn where to +access database information as needed. To administer the +B file, use the following commands: C, C, C, and C. + +=item * + +The B file lists the server encryption keys +that the server processes use to decrypt tickets presented by +client processes and one another. To administer the KeyFile file, +use the following commands: C, C, and C. + +=item * + +The B file defines the cell to which the +server machine belongs for the purposes of server-to-server +communication. Administer it with the C command. +There is also a B file that defines the +machine's cell membership with respect to the AFS command suites +and Cache Manager access to AFS data. + +=item * + +The B file lists the user name of each +administrator authorized to issue privileged C and C commands. +To administer the UserList file, use the following commands: C, C, and C. + +=item * + +The B file defines which AFS server +processes run on the server machine, and whether the BOS Server +restarts them automatically if they fail. It also defines when all +processes restart automatically (by default once per week), and +when the BOS Server restarts processes that have new binary files +(by default once per day). To administer the BosConfig file, use +the following commands: C, C, C, +C, C, and C. + +=item * + +The B file records important operations the BOS +Server performs and error conditions it encounters. + +=back + +For more details, see the reference page for each file. + +=head1 OPTIONS + +The following arguments and flags are available on many commands in +the C suite. The reference page for each command also lists them, +but they are described here in greater detail. + +=over 4 + +=item B<-cell> I + +Names the cell in which to run the command. It is acceptable to +abbreviate the cell name to the shortest form that +distinguishes it from the other entries in the +B file on the local machine. If the +B<-cell> argument is omitted, the command interpreter determines +the name of the local cell by reading the following in order: + +=over + +=item 1. + +The value of the AFSCELL environment variable + +=item 2. + +The local B file + +=back + +Do not combine the B<-cell> and B<-localauth> options. A command on +which the B<-localauth> flag is included always runs in the local +cell (as defined in the server machine's local +B file), whereas a command on which the +B<-cell> argument is included runs in the specified foreign cell. + +=item B<-help> + +Prints a command's online help message on the standard output +stream. Do not combine this flag with any of the command's +other options; when it is provided, the command interpreter +ignores all other options, and only prints the help message. + +=item B<-localauth> + +Constructs a server ticket using the server encryption key with +the highest key version number in the local +B file. The C command interpreter presents +the ticket, which never expires, to the BOS Server during +mutual authentication. + +Use this flag only when issuing a command on a server machine; +client machines do not usually have a B +file. The issuer of a command that includes this flag must be +logged on to the server machine as the local superuser B. +The flag is useful for commands invoked by an unattended +application program, such as a process controlled by the UNIX +B utility or by a cron entry in the machine's +B file. It is also useful if an +administrator is unable to authenticate to AFS but is logged in +as the local superuser B. + +Do not combine the B<-cell> and B<-localauth> options. A command on +which the B<-localauth> flag is included always runs in the local +cell (as defined in the server machine's local +B file), whereas a command on which the +B<-cell> argument is included runs in the specified foreign cell. +Also, do not combine the B<-localauth> and B<-noauth> flags. + +=item B<-noauth> + +Establishes an unauthenticated connection to the BOS Server, in +which the BOS Server treats the issuer as the unprivileged user +B. It is useful only when authorization checking is +disabled on the server machine (during the installation of a +file server machine or when the C command has been +used during other unusual circumstances). In normal +circumstances, the BOS Server allows only privileged users to +issue commands that change the status of a server or +configuration file, and refuses to perform such an action even +if the B<-noauth> flag is provided. Do not combine the B<-noauth> and +B<-localauth> flags. + +=item B<-server> I + +Indicates the AFS server machine on which to run the command. +Identify the machine by its IP address in dotted decimal +format, its fully-qualified host name (for example, +B), or by an abbreviated form of its host name that +distinguishes it from other machines. Successful use of an +abbreviated form depends on the availability of a name service +(such as the Domain Name Service or a local host table) at the +time the command is issued. + +For the commands that alter the administrative files shared by +all server machines in the cell (the C, C, +C, C, C, and C +commands), the appropriate machine depends on whether the cell +uses the United States or international version of AFS: + +=over + +=item * + +If the cell runs the United States edition of AFS and (as +recommended) uses the Update Server to distribute the +contents of the B directory, provide the name of +the system control machine. After issuing the command, allow +up to five minutes for the Update Server to distribute the +changed file to the other AFS server machines in the cell. If +the specified machine is not the system control machine but +is running an B process that refers to the system +control machine, then the change will be overwritten when the +process next brings over the relevant file from the system +control machine. + +=item * + +If the cell runs the international edition of AFS, do not use +the Update Server to distribute the contents of the +B directory. Instead, repeatedly issue the +command, naming each of the cell's server machines in turn. +To avoid possible inconsistency problems, finish issuing the +commands within a fairly short time. + +=back + +=back + +=head1 PRIVILEGE REQUIRED + +To issue any C command that changes a configuration file or alters +process status, the issuer must be listed in the B +file on the server machine named by the B<-server> argument. +Alternatively, if the B<-localauth> flag is included the issuer must be +logged on as the local superuser B. + +To issue a C command that only displays information (other than the +C command), no privilege is required. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_addhost.pod b/doc/man-pages/pod/bos_addhost.pod new file mode 100644 index 0000000000..01188738e4 --- /dev/null +++ b/doc/man-pages/pod/bos_addhost.pod @@ -0,0 +1,124 @@ +=head1 NAME + +bos addhost - Adds a database server machine to the B file + +=head1 SYNOPSIS + +bos addhost B<-server> I B<-host> I [I ...] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos addh B<-s> I B<-ho> I [I ...] +[B<-c> I] [B<-n>] [B<-l>] [B<-he>] + +=head1 DESCRIPTION + +The C command adds an entry for each database server machine +specified with the B<-host> argument to the B file +on the machine named by the B<-server> argument. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Identifies the server machine on which to change the +B file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +In cells that run the United States edition of AFS and use the +Update Server to distribute the contents of the B +directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. In cells +that run the international version of AFS, repeat the command +for each file server machine. For further discussion, see the +introductory reference page for the C command suite. + +=item B<-host> I [I ...] + +Specifies the fully-qualified host name (such as B) +of each database server machine to register in the B +file. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command adds the database server machines B +and B to the B file on the machine +B (the system control machine). + + bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +After executing this command (and waiting for the Update Server to +propagate the changes, if it is used), restart the database server +processes on all database server machines to force election of a +quorum that includes the new set of machines listed in the +B file. The IBM AFS Quick Beginnings explains in +more detail how to add and remove database server machines. + +It is best to maintain a one-to-one mapping between hostnames and IP +addresses on a multihomed database server machine (this is actually +the conventional configuration for any AFS machine). The BOS Server +uses the B routine to obtain the IP address associated +with the hostname specified by the -host argument. If there is more +than one address, the BOS Server records in the B entry the +one that appears first in the list of addresses returned by the +routine. The routine possibly returns addresses in a different order +on different machines, which can create inconsistency. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +IBM AFS Quick Beginnings + +=cut diff --git a/doc/man-pages/pod/bos_addkey.pod b/doc/man-pages/pod/bos_addkey.pod new file mode 100644 index 0000000000..2787f0962d --- /dev/null +++ b/doc/man-pages/pod/bos_addkey.pod @@ -0,0 +1,141 @@ +=head1 NAME + +bos addkey - Adds a new server encryption key to the B file + +=head1 SYNOPSIS + +bos addkey B<-server> I [B<-key> I] +B<-kvno> I [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos addk B<-s> I [B<-ke> I] B<-kv> I +[B<-ce> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command constructs a server encryption key from the +text string provided, assigns it the key version number specified with +the B<-kvno> argument, and adds it to the B file on +the machine specified with the B<-server> argument. Be sure to use the +C or C command to add the same key to the B +entry in the Authentication Database. + +Do not use the B<-key> argument, which echoes the password string visibly +on the screen. If the argument is omitted, the BOS Server prompts for +the string and does not echo it visibly: + + Input key: + Retype input key: + +The BOS Server prohibits reuse of any key version number already +listed in the B file. This ensures that users who +still have tickets sealed with the current key are not prevented from +communicating with a server process because the current key is +overwritten with a new key. Use the C command to display +the key version numbers in the B file. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to change the +B file. Identify the machine by IP address +or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +In cells that run the United States edition of AFS and use the +Update Server to distribute the contents of the B +directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. In cells +that run the international version of AFS, repeat the command +for each file server machine. For further discussion, see the +introductory reference page for the C command suite. + +=item B<-key> I + +Specifies a character string just like a password; the BOS +Server calls a DES conversion function to encode it into a form +appropriate for use as an encryption key. Omit this argument to +have the BOS Server prompt for the string instead. + +=item B<-kvno> I + +Defines the new key's key version number. It must be an integer +in the range from B<0> (zero) through B<255>. For the sake of +simplicity, use the number one higher than the current highest +key version number; use the C command to display key +version numbers. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the strings typed at the C and C prompts do +not match, the following message appears, and the command exits +without adding a new key: + + Input key mismatch + +=head1 EXAMPLES + +The following command adds a new server encryption key with key +version number 14 to the B file kept on the machine B +(the system control machine). The issuer omits the B<-key> argument, as +recommended, and provides the password at the prompts. + + bos addkey -server fs1.abc.com -kvno 14 + Input key: + Retype input key: + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_adduser.pod b/doc/man-pages/pod/bos_adduser.pod new file mode 100644 index 0000000000..69acd1ea75 --- /dev/null +++ b/doc/man-pages/pod/bos_adduser.pod @@ -0,0 +1,104 @@ +=head1 NAME + +bos adduser - Adds a privileged user to the B file + +=head1 SYNOPSIS + +bos adduser B<-server> I B<-user> I [I ...] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos addu B<-s> I B<-u> I [I ...] +[B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command adds each user name specified with the B<-user> +argument to the B file on the machine named by the +B<-server> argument. It is the issuer's responsibility to verify that an +entry for the user exists in the Authentication and Protection +Databases. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to change the +B file. Identify the machine by IP address +or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +In cells that run the United States edition of AFS and use the +Update Server to distribute the contents of the B +directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. In cells +that run the international version of AFS, repeat the command +for each file server machine. For further discussion, see the +introductory reference page for the C command suite. + +=item B<-user> I [I ...] + +Specifies each user name to insert into the +B file. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command adds the user names pat and smith to the +B file on the machine B (the system +control machine). + + bos adduser -server fs1.abc.com -user pat smith + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_apropos.pod b/doc/man-pages/pod/bos_apropos.pod new file mode 100644 index 0000000000..df4f3c2711 --- /dev/null +++ b/doc/man-pages/pod/bos_apropos.pod @@ -0,0 +1,70 @@ +=head1 NAME + +bos apropos - Displays each help entry containing a keyword string + +=head1 SYNOPSIS + +bos apropos B<-topic> I [B<-help>] + +bos ap B<-t> I [B<-h>] + +=head1 DESCRIPTION + +The C command displays the first line of the online help +entry for any C command that has in its name or short description +the string specified by the B<-topic> argument. + +To display the syntax for a command, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I + +Specifies the keyword string to match, in lowercase letters +only. If the string is more than a single word, surround it +with double quotes ("") or other delimiters. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of a command's online help entry names it and briefly +describes its function. This command displays the first line for any +C command where the string specified with the B<-topic> argument is +part of the command name or first line. + +=head1 EXAMPLES + +The following command lists all C commands that include the word +B in their names or short descriptions: + + bos apropos restart + getrestart: get restart times + restart: restart all processes + setrestart: set restart times + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_create.pod b/doc/man-pages/pod/bos_create.pod new file mode 100644 index 0000000000..3107fea3d5 --- /dev/null +++ b/doc/man-pages/pod/bos_create.pod @@ -0,0 +1,410 @@ +=head1 NAME + +bos create - Defines a new process in the B file and starts +it running + +=head1 SYNOPSIS + +bos create B<-server> I B<-instance> I +B<-type> I B<-cmd> I [I ...] +[B<-notifier> I] [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos c B<-s> I B<-i> I B<-t> I +B<-cm> I [I ...] [B<-not> I] [B<-ce> I] +[B<-noa>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command creates a server process entry in the +B file on the server machine named by the +B<-server> argument, sets the process's status to B in the B +file and in memory, and starts the process. + +A server process's entry in the B file defines its name, its +type, the command that initializes it, and optionally, the name of a +notifier program that runs when the process terminates. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to define and start the +new process. Identify the machine by IP address or its host +name (either fully-qualified or abbreviated unambiguously). For +details, see the introductory reference page for the C +command suite. + +=item B<-instance> I + +Names the process to define and start. Any name is acceptable, +but for the sake of simplicity it is best to use the last +element of the process's binary file pathname, and to use the +same name on every server machine. The conventional names, as +used in all AFS documentation, are: + +=over + +=item B + +The Backup Server process + +=item B + +The process that combines the File Server, Volume Server, +and Salvager processes (B, B, and +B) + +=item B + +The Authentication Server process + +=item B + +The Protection Server process + +=item B + +The controller process for the Network Time Protocol +Daemon + +=item B + +The client portion of the Update Server process that +retrieves binary files from the B directory of +the binary distribution machine for this machine's +CPU/operating system type. (The name of the binary is +B, but the B suffix distinguishes this process +from B.) + +=item B + +The client portion of the Update Server process that +retrieves configuration files from the B +directory of the system control machine. Do not run this +process in cells that use the international edition of +AFS. (The name of the binary is B, but the B +suffix distinguishes this process from B.) + +=item B + +The server portion of the Update Server process + +=item B + +The Volume Location (VL) Server process + +=back + +=item B<-type> I + +Specifies the process's type. The acceptable values are: + +=over + +=item B + +Use this value for cron-type processes that the BOS +Server starts only at a defined daily or weekly time, +rather than whenever it detects that the process has +terminated. AFS does not define any such processes by +default, but makes this value available for administrator +use. Define the time for command execution as part of the +B<-cmd> argument to the C command. + +=item B + +Use this value only for the B process, which combines +the File Server, Volume Server and Salvager processes. If +one of the component processes terminates, the BOS Server +shuts down and restarts the processes in the appropriate +order. + +=item B + +Use this value for all processes listed as acceptable +values to the B<-instance> argument, except for the B +process. There are no interdependencies between simple +processes, so the BOS Server can stop and start them +independently as necessary. + +=back + +=item B<-cmd> I [I ...] + +Specifies each command the BOS Server runs to start the +process. Specify no more than six commands (which can include +the command's options, in which case the entire string is +surrounded by double quotes); any additional commands are +ignored. + +For a simple process, provide the complete pathname of the +process's binary file on the local disk (for example, +B for the Protection Server). If including +any of the initialization command's options, surround the +entire command in double quotes (" "). The B process has +a required argument, and the commands for all other processes +take optional arguments. + +For the B process, provide the complete pathname of the local +disk binary file for each of the component processes: +B, B, and B, in that order. The +standard binary directory is B. If including any of +an initialization command's options, surround the entire +command in double quotes (B<" ">). + +For a B process, provide two parameters: + +=over + +=item * + +The complete local disk pathname of either an executable file +or a command from one of the AFS suites (complete with all of +the necessary arguments). Surround this parameter with double +quotes (B<" ">) if it contains spaces. + +=item * + +A specification of when the BOS Server executes the file or +command indicated by the first parameter. There are three +acceptable values: + +=over + +=item * + +The string C, which directs the BOS Server to execute +the file or command immediately and only once. It is +usually simpler to issue the command directly or issue +the C command. + +=item * + +A time of day. The BOS Server executes the file or +command daily at the indicated time. Separate the hours +and minutes with a colon (I:I), and use either 24-hour +format, or a value in the range from B<1:00> through B<12:59> +with the addition of B or B. For example, both B<14:30> +and B<"2:30 pm"> indicate 2:30 in the afternoon. Surround +this parameter with double quotes (B<" ">) if it contains a +space. + +=item * + +A day of the week and time of day, separated by a space +and surrounded with double quotes (B<" ">). The BOS Server +executes the file or command weekly at the indicated day +and time. For the day, provide either the whole name or +the first three letters, all in lowercase letters +(B or B, B or B, and so on). For the +time, use the same format as when specifying the time +alone. + +=back + +=back + +=item B<-notifier> I + +Specifies the complete pathname on the local disk of a program +that the BOS Server invokes when the process terminates. The +AFS distribution does not include any notifier programs, but +this argument is available for administrator use. See the +L section. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command defines and starts the simple process kaserver +on the machine B: + + bos create -server fs3.abc.com -instance kaserver -type simple \ + -cmd /usr/afs/bin/kaserver + +The following command defines and starts the simple process +B on the machine B. It references B as +the source for updates to binary files, checking for changes to the +B directory every 120 seconds. + + bos create -server fs4.abc.com -instance upclientbin -type simple \ + -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \ + /usr/afs/bin" + +The following command creates the fs process B on the machine +B. Type the command on a single line. + + bos create -server fs4.abc.com -instance fs -type fs \ + -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \ + /usr/afs/bin/salvager + +The following command creates a B process called B on the +machine B, so that the BOS Server issues the indicated C command each day at 3:00 a.m. (the command creates a backup +version of every volume in the file system whose name begins with +B). Note that the issuer provides the complete pathname to the C +command, includes the B<-localauth> flag on it, and types the entire C command on one line. + + bos create -server fs5.abc.com -instance userbackup -type cron \ + -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 Related Information + +If the B<-notifier> argument is included when this command is used to +define and start a process, the BOS Server invokes the indicated +I when the process exits. The intended use of a +notifier program is to inform administrators when a process exits +unexpectedly, but it can be used to perform any appropriate actions. +The following paragraphs describe the B and B structures +in which the BOS Server records information about the exiting process. +The list of AFS commands related to this one follows. + +The BOS Server constructs and sends on the standard output stream one +B and one B structure for each exiting process associated +with the notifier program. It brackets each structure with appropriate +C and C statements (C and C, C +and C), which immediately follow the preceding newline +character with no intervening spaces or other characters. If the +notifier program does not need information from a structure, it can +scan ahead in the input stream for the C statement. + +In general, each field in a structure is a string of ASCII text +terminated by the newline character. The format of the information +within a structure possibly varies slightly depending on the type of +process associated with the notifier program. + +The C code for the B and B structures follows. Note that +the structures sent by the BOS Server do not necessarily include all +of the fields described here, because some are used only for internal +record keeping. The notifier process must robustly handle the absence +of expected fields, as well as the presence of unexpected fields, on +the standard input stream. + +For proper performance, the notifier program must continue processing +the input stream until it detects the end-of-file (EOF). The BOS +Server closes the standard input file descriptor to the notifier +process when it has completed delivery of the data, and it is the +responsibility of the notifier process to terminate properly. + +=head2 struct bnode contents + + struct bnode { + struct bnode *next; /* next pointer in top-level's list */ + char *name; /* instance name */ + long nextTimeout; /* next time this guy should be awakened */ + long period; /* period between calls */ + long rsTime; /* time we started counting restarts */ + long rsCount; /* count of restarts since rsTime */ + struct bnode_type *type; /* type object */ + struct bnode_ops *ops; /* functions implementing bnode class */ + long procStartTime; /* last time a process was started */ + long procStarts; /* number of process starts */ + long lastAnyExit; /* last time a process exited for any reason */ + long lastErrorExit; /* last time a process exited unexpectedly */ + long errorCode; /* last exit return code */ + long errorSignal; /* last proc terminating signal */ + char *lastErrorName; /* name of proc that failed last */ + short refCount; /* reference count */ + short flags; /* random flags */ + char goal; /* 1=running or 0=not running */ + char fileGoal; /* same, but to be stored in file */ + }; + +=head2 format of struct bnode explosion + + printf("name: %s\n",tp->name); + printf("rsTime: %ld\n", tp->rsTime); + printf("rsCount: %ld\n", tp->rsCount); + printf("procStartTime: %ld\n", tp->procStartTime); + printf("procStarts: %ld\n", tp->procStarts); + printf("lastAnyExit: %ld\n", tp->lastAnyExit); + printf("lastErrorExit: %ld\n", tp->lastErrorExit); + printf("errorCode: %ld\n", tp->errorCode); + printf("errorSignal: %ld\n", tp->errorSignal); + printf("lastErrorName: %s\n", tp->lastErrorName); + printf("goal: %d\n", tp->goal); + +=head2 struct bnode_proc contents + + struct bnode_proc { + struct bnode_proc *next; /* next guy in top-level's list */ + struct bnode *bnode; /* bnode creating this process */ + char *comLine; /* command line used to start this process */ + char *coreName; /* optional core file component name */ + long pid; /* pid if created */ + long lastExit; /* last termination code */ + long lastSignal; /* last signal that killed this guy */ + long flags; /* flags giving process state */ + }; + +=head2 format of struct bnode_proc explosion + + printf("comLine: %s\n", tp->comLine); + printf("coreName: %s\n", tp->coreName); + printf("pid: %ld\n", tp->pid); + printf("lastExit: %ld\n", tp->lastExit); + printf("lastSignal: %ld\n", tp->lastSignal); + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_delete.pod b/doc/man-pages/pod/bos_delete.pod new file mode 100644 index 0000000000..684287e800 --- /dev/null +++ b/doc/man-pages/pod/bos_delete.pod @@ -0,0 +1,101 @@ +=head1 NAME + +bos delete - Deletes a server process from the B file + +=head1 SYNOPSIS + +bos delete B<-server> I B<-instance> I [I ...] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos d B<-s> I B<-i> I [I ...] [B<-c> I] +[B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command removes the B entry for +each process indicated by the B<-instance> argument, on the server +machine named by the B<-server> argument. + +Before issuing this command, issue the C command to stop the +process and set its status flag in the B file to C. The +C command fails with an error message if a process's status +flag is C. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to delete the server +process entry from the B file. Identify +the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see +the introductory reference page for the C command suite. + +=item B<-instance> I [I ...] + +Names each process to delete. Use the name assigned with the +B<-instance> argument to the C command; process names +appear in the output of the C command. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command removes the B, B, B, and +B entries from the B file on B, a database +server machine being decommissioned. + + bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_exec.pod b/doc/man-pages/pod/bos_exec.pod new file mode 100644 index 0000000000..1f1210d5f2 --- /dev/null +++ b/doc/man-pages/pod/bos_exec.pod @@ -0,0 +1,90 @@ +=head1 NAME + +bos exec - Executes a command on a remote server machine + +=head1 SYNOPSIS + +bos exec B<-server> I B<-cmd> I +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos e B<-s> I B<-cm> I [B<-ce> I] +[B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command executes the indicated command on the file server +machine named by the B<-server> argument. Its intended use is to reboot +the machine, using the B command or equivalent. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to execute the command. +Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see +the introductory reference page for the C command suite. + +=item B<-cmd> I + +Specifies the complete local disk pathname of the command to +execute (for example, B). Surround this argument with +double quotes ("") if the command contains one or more spaces. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command reboots the machine B. The issuer has +previously issued the C command to shutdown all processes +cleanly. + + bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/bos_getdate.pod b/doc/man-pages/pod/bos_getdate.pod new file mode 100644 index 0000000000..ed67b62e28 --- /dev/null +++ b/doc/man-pages/pod/bos_getdate.pod @@ -0,0 +1,119 @@ +=head1 NAME + +bos getdate - Displays the time stamps on an AFS binary file + +=head1 SYNOPSIS + +bos getdate B<-server> I B<-file> I [I ...] +[B<-dir> I] [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos getd B<-s> I B<-f> I [I ...] [B<-d> I] +[B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the time stamps on the current +version, C<.BAK> version (if any) and C<.OLD> version (if any) of each +binary file named by the B<-file> argument. (The BOS Server automatically +creates C<.BAK> and C<.OLD> versions when new binaries are installed with +the C command.) The files must reside in the B +directory on the server machine named by the B<-server> argument unless +the B<-dir> argument indicates an alternate directory. + +To revert to the C<.BAK> version of a binary, use the C +command. To remove obsolete binary files from the B +directory, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine from which to list binary files. +Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see +the introductory reference page for the C command suite. + +All server machines of the same AFS system type show the same +timestamps if the binaries were installed properly on the +binary distribution machine for this machine's system type, and +if all other machines of that type are running the appropriate +B process. + +=item B<-file> I [I ...] + +Names each binary file to list. + +=item B<-dir> I + +Specifies the complete pathname of the local disk directory +containing each file named by the B<-file> argument. It is +necessary only if the files are not in the B +directory. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +For each file specified with the B<-file> argument, the output displays +the time stamp on the current (unmarked), C<.BAK>, and C<.OLD> version. The +output explicitly reports that a version does not exist, rather than +simply omitting it. + +=head1 EXAMPLES + +The following command examines the time stamps on the files with +basename B on the machine B: + + bos getdate -server fs2.abc.com -file kaserver + File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999. + .BAK file dated Wed Dec 9 18:55:04 1998, no .OLD file. + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_getlog.pod b/doc/man-pages/pod/bos_getlog.pod new file mode 100644 index 0000000000..6d3a97b954 --- /dev/null +++ b/doc/man-pages/pod/bos_getlog.pod @@ -0,0 +1,154 @@ +=head1 NAME + +bos getlog - Prints a server process's log file + +=head1 SYNOPSIS + +bos getlog B<-server> I B<-file> I +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos getl B<-s> I B<-f> I [B<-c> I] +[B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command displays on the standard output stream the +specified log file from the machine named by the B<-server> argument. The +BOS Server fetches the log file from the B directory +unless an alternate pathname is provided as part of the B<-file> +argument. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine from which to retrieve the log +file. Identify the machine by IP address or its host name +(either fully-qualified or abbreviated unambiguously). For +details, see the introductory reference page for the C +command suite. + +=item B<-file> I + +Names the log file to display. If a filename only is provided, +the BOS Server fetches the log file from the B +directory; the standard values are: + +=over + +=item B + +The Authentication Server (B) log file + +=item B + +The Backup Server (B) log file + +=item B + +The BOS Server (B) log file + +=item B + +The File Server (B) log file + +=item B + +The Salvager (B) log file + +=item B + +The Volume Location (VL) Server (B) log file + +=item B + +The Volume Server (B) log file + +=back + +If a pathname and filename are provided, the log file is +retrieved from the indicated directory. Partial pathnames are +interpreted relative to the B directory. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output is preceded by the line + +Fetching log file 'I'... + +The remainder of the output depends on the particular log file. + +=head1 EXAMPLES + +The following example displays the B file from the machine +B: + + bos getlog -server fs3.abc.com -file FileLog + Fetching log file 'FileLog'... + Sun Nov 8 04:00:34 1998 File server starting + Sun Nov 8 04:00:39 1998 Partition /vicepa: attached 21 volumes; + 0 volumes not attached + Sun Nov 8 04:00:40 1998 File Server started Sun Nov 8 04:00:40 + 1998 + Mon Nov 9 21:45:06 1998 CB: RCallBack (zero fid probe in host.c) + failed for host 28cf37c0.22811 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Log files can grow quite large, especially for the database server +processes. To keep them to a manageable size, periodically either use +the UNIX B command to truncate each log file, or use the C +command to restart each process. + +It can take up to five minutes after the file is removed or process +restarted for the space occupied by a log file to become available. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/bos_getrestart.pod b/doc/man-pages/pod/bos_getrestart.pod new file mode 100644 index 0000000000..afb810ec55 --- /dev/null +++ b/doc/man-pages/pod/bos_getrestart.pod @@ -0,0 +1,151 @@ +=head1 NAME + +bos getrestart - Displays the automatic restart times for server processes + +=head1 SYNOPSIS + +bos getrestart B<-server> I [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos getr B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command displays two restart times from the +B file on the server machine named by the +B<-server> argument: + +=over + +=item * + +The I at which the BOS Server process +automatically restarts itself and all processes marked with status +Run in the B file. The default is Sunday at 4:00 a.m. + +=item * + +The binary restart time at which the BOS Server automatically +restarts any process for which the time stamp on the binary file +in the B directory is later than the last restart time +for the process. The default is 5:00 a.m. Use the C +command to list a binary file's timestamp, and the B<-long> flag to +the C command to display a process's most recent restart +time. + +=back + +Use the C command to set the restart times. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine for which to display the restart +times. Identify the machine by IP address or its host name +(either fully-qualified or abbreviated unambiguously). For +details, see the introductory reference page for the C +command suite. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output consists of two lines: + +Server I restarts at I to the file +B on the machine B, which is the binary +distribution machine for server machines running AIX 4.2 in the +B cell. The current version of the B file is +moved to B. + + bos install -server fs3.abc.com \ + -file /afs/abc.com/rs_aix42/usr/afs/bin/vlserver + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_listhosts.pod b/doc/man-pages/pod/bos_listhosts.pod new file mode 100644 index 0000000000..954c0cb2ad --- /dev/null +++ b/doc/man-pages/pod/bos_listhosts.pod @@ -0,0 +1,111 @@ +=head1 NAME + +bos listhosts - Displays the contents of the B file + +=head1 SYNOPSIS + +bos listhosts B<-server> I [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos listh B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +bos getcell B<-server> I [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos getc B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command formats and displays the list of a cell's +database server machines from the B file on the +server machine named by the B<-server> argument. + +To alter the list of machines, use the C and C +commands. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine from which to display the +B file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +For consistent performance in the cell, the output must be the +same on every server machine. The L reference page +explains how to keep the machines synchronized. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of the output names the cell to which the server +machine belongs. Each of the following lines names a database server +machine for that cell. + +The Host number assigned to each database server machine is for +server-internal use only and is not the same as, nor necessarily +related to, the machine's IP address. The BOS Server assigned it as +part of performing the C command. + +=head1 EXAMPLES + +The following command displays the database server machines listed in +the B file on the machine B. + + bos listhosts fs7.abc.com + Cell name is abc.com + Host 1 is db1.abc.com + Host 2 is db2.abc.com + Host 3 is db3.abc.com + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_listkeys.pod b/doc/man-pages/pod/bos_listkeys.pod new file mode 100644 index 0000000000..f372b00eaf --- /dev/null +++ b/doc/man-pages/pod/bos_listkeys.pod @@ -0,0 +1,142 @@ +=head1 NAME + +bos listkeys - Displays the server encryption keys from the B file + +=head1 SYNOPSIS + +bos listkeys B<-server> I [B<-showkey>] [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos listk B<-se> I [B<-sh>] [B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command formats and displays the list of server +encryption keys from the B file on the server +machine named by the B<-server> argument. + +To edit the list of keys, use the C and C +commands. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine from which to display the B +file. Identify the machine by IP address or its host name +(either fully-qualified or abbreviated unambiguously). For +details, see the introductory reference page for the C +command suite. + +For consistent performance in the cell, the output must be the +same on every server machine. The L reference page +explains how to keep the machines synchronized. + +=item B<-showkey> + +Displays the octal digits that constitute each key. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output includes one line for each server encryption key listed in +the B file, identified by its key version number. + +If the B<-showkey> flag is included, the output displays the actual +string of eight octal numbers that constitute the key. Each octal +number is a backslash and three decimal digits. + +If the B<-showkey> flag is not included, the output represents each key +as a checksum, which is a decimal number derived by encrypting a +constant with the key. + +Following the list of keys or checksums, the string C +indicates when a key was last added to the B file. The words C indicate the end of the output. + +For mutual authentication to work properly, the output from the +command B must match the key or checksum with the same +key version number in the output from this command. + +=head1 EXAMPLES + +The following example shows the checksums for the keys stored in the +B file on the machine B. + + bos listkeys fs3.abc.com + key 1 has cksum 972037177 + key 3 has cksum 2825175022 + key 4 has cksum 260617746 + key 6 has cksum 4178774593 + Keys last changed on Mon Apr 12 11:24:46 1999. + All done. + +The following example shows the actual keys from the B file on +the machine B. + + bos listkeys fs6.abc.com -showkey + key 0 is '\040\205\211\241\345\002\023\211' + key 1 is '\343\315\307\227\255\320\135\244' + key 2 is '\310\310\255\253\326\236\261\211' + Keys last changed on Wed Mar 31 11:24:46 1999. + All done. + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Displaying actual keys on the standard output stream (by including the +B<-showkey> flag) is a security exposure. Displaying a checksum is +sufficient for most purposes. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_listusers.pod b/doc/man-pages/pod/bos_listusers.pod new file mode 100644 index 0000000000..ca218541ba --- /dev/null +++ b/doc/man-pages/pod/bos_listusers.pod @@ -0,0 +1,98 @@ +=head1 NAME + +bos listusers - Lists the privileged users from the B file + +=head1 SYNOPSIS + +bos listusers B<-server> I [B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos listu B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command lists the user names from the +B file on the file server machine named by the +B<-server> argument. The users are authorized to issue privileged C and +C commands. + +To edit the list of users, use the C and C +commands. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine from which to display the B +file. Identify the machine by IP address or its host name +(either fully-qualified or abbreviated unambiguously). For +details, see the introductory reference page for the C +command suite. + +For consistent performance in the cell, the output must be the +same on every server machine. The L reference page +explains how to keep the machines synchronized. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output lists the user name of each user entitled to issue +privileged C and C commands. + +=head1 EXAMPLES + +The following example lists the users from B file on the +machine B. + + bos listusers fs4.abc.com + SUsers are: pat smith jones terry + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_prune.pod b/doc/man-pages/pod/bos_prune.pod new file mode 100644 index 0000000000..987db181a9 --- /dev/null +++ b/doc/man-pages/pod/bos_prune.pod @@ -0,0 +1,144 @@ +=head1 NAME + +bos prune - Removes obsolete versions of files from the B and +B directories + +=head1 SYNOPSIS + +bos prune B<-server> I [B<-bak>] [B<-old>] [B<-core>] [B<-all>] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos p B<-s> I [B<-b>] [B<-o>] [B<-co>] [B<-a>] +[B<-ce> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command removes files from the local disk of the server +machine named by the B<-server> argument, as specified by one or more of +the following flags provided on the command line: + +=over + +=item * + +The B<-bak> flag removes all files from the B directory +that have a C<.BAK> extension. + +=item * + +The B<-old> flag removes all files from the B directory +that have a C<.OLD> extension. + +=item * + +The B<-core> flag removes all files from the B directory +that have a C prefix. + +=item * + +The B<-all> flag removes all three types of files at once. + +=back + +(If none of these flags are included, the command appears to succeed, +but removes no files at all.) + +To display the timestamp on the current, C<.BAK>, and C<.OLD> versions of +one or more files, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine from which to remove files. +Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see +the introductory reference page for the C command suite. + +=item B<-bak> + +Removes all files from the B directory that have a +C<.BAK> extension. Do not combine this flag and the B<-all> flag. + +=item B<-old> + +Removes all files from the B directory that have a +C<.OLD> extension. Do not combine this flag and the B<-all> flag. + +=item B<-core> + +Removes all files from the B directory that have a +C prefix. Do not combine this flag and the B<-all> flag. + +=item B<-all> + +Combines the effect of the B<-bak>, B<-old>, and B<-core> flags. Do not +combine this flag with any of those three. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example removes all files from the B +directory on the machine B that have a C<.BAK> or C<.OLD> +extension. + + bos prune -server fs3.abc.com -bak -old + +The following example removes all files from the B +directory on the machine B that have a C<.BAK> or C<.OLD> +extension, and all files from the B directory that have a +C prefix. + + bos prune -server db2.abc.com -all + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_removehost.pod b/doc/man-pages/pod/bos_removehost.pod new file mode 100644 index 0000000000..8bf34a2b3e --- /dev/null +++ b/doc/man-pages/pod/bos_removehost.pod @@ -0,0 +1,115 @@ +=head1 NAME + +bos removehost - Removes a database server machine from the B +file + +=head1 SYNOPSIS + +bos removehost B<-server> I B<-host> I [I ...] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos removeh B<-s> I B<-ho> I [I ...] [B<-c> I] +[B<-n>] [B<-l>] [B<-he>] + +=head1 DESCRIPTION + +The C command removes the entry for each database server +machine specified with the B<-host> argument from the +B file on the server machine named by the +B<-server> argument. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to change the +B file. Identify the machine by IP +address or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +In cells that run the United States edition of AFS and use the +Update Server to distribute the contents of the B +directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. In cells +that run the international version of AFS, repeat the command +for each file server machine. For further discussion, see the +introductory reference page for the C command suite. + +=item B<-host> I [I ...] + +Specifies the fully-qualified host name (such as B) +of each database server machine to remove from the B +file. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command removes the former database server machine +B from the B file on the system control machine +B. + + bos removehost -server fs1.abc.com -host db2.abc.com + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +After executing this command (and waiting for the Update Server to +propagate the changes, if it is used), restart the database server +processes on all database server machines to force election of a +quorum that includes the new set of machines listed in the +B file. The IBM AFS Quick Beginnings explains in +more detail how to add and remove database server machines. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +IBM_AFS Quick_Beginnings + +=cut diff --git a/doc/man-pages/pod/bos_removekey.pod b/doc/man-pages/pod/bos_removekey.pod new file mode 100644 index 0000000000..261c61e4b7 --- /dev/null +++ b/doc/man-pages/pod/bos_removekey.pod @@ -0,0 +1,109 @@ +=head1 NAME + +bos removekey - Removes a server encryption key from the B file + +=head1 SYNOPSIS + +bos removekey B<-server> I B<-kvno> I [I ...] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos removek B<-s> I B<-k> I [I ...] +[B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command removes each specified encryption key from +the B file on the machine named by the B<-server> +argument. Use the B<-kvno> argument to identify each key by its key +version number; use the C command to display the key +version numbers. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to change the +B file. Identify the machine by IP address +or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +In cells that run the United States edition of AFS and use the +Update Server to distribute the contents of the B +directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. In cells +that run the international version of AFS, repeat the command +for each file server machine. For further discussion, see the +introductory reference page for the C command suite. + +=item B<-kvno> I [I ...] + +Specifies the key version number of each key to remove. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command removes the keys with key version numbers 5 and +6 from the B file on the system control machine B. + + bos removekey -server fs1.abc.com -kvno 5 6 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Before removing a obsolete key, verify that the cell's maximum ticket +lifetime has passed since the current key was defined using the C and C commands. This ensures that no clients +still possess tickets encrypted with the obsolete key. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_removeuser.pod b/doc/man-pages/pod/bos_removeuser.pod new file mode 100644 index 0000000000..5b846930e3 --- /dev/null +++ b/doc/man-pages/pod/bos_removeuser.pod @@ -0,0 +1,100 @@ +=head1 NAME + +bos removeuser - Removes a privileged user from the B file + +=head1 SYNOPSIS + +bos removeuser B<-server> I B<-user> I [I ...] +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos removeu B<-s> I B<-u> I [I ...] [B<-c> I] +[B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command removes each user name specified with the +B<-user> argument from the B file on the machine +named by the B<-server> argument. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to change the +B file. Identify the machine by IP address +or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +In cells that run the United States edition of AFS and use the +Update Server to distribute the contents of the B +directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. In cells +that run the international version of AFS, repeat the command +for each file server machine. For further discussion, see the +introductory reference page for the C command suite. + +=item B<-user> I [I ...] + +Specifies each user name to remove. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example removes the users B and B from the +B file on the system control machine B. + + bos removeuser -server fs1.abc.com -user pat jones + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_restart.pod b/doc/man-pages/pod/bos_restart.pod new file mode 100644 index 0000000000..beb2848365 --- /dev/null +++ b/doc/man-pages/pod/bos_restart.pod @@ -0,0 +1,152 @@ +=head1 NAME + +bos restart - Restarts a server process + +=head1 SYNOPSIS + +bos restart B<-server> I [B<-instance> I [I ...]] [B<-bosserver>] +[B<-all>] [B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos res B<-s> I [B<-i> I [I ...]] [B<-b>] [B<-a>] +[B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command stops and immediately restarts server +processes on the server machine named by the B<-server> argument. +Indicate which process or processes to restart by providing one of the +following arguments: + +=over + +=item * + +The B<-instance> argument names each AFS server process to stop and +restart immediately, regardless of its status flag in the +B file. Do not include B in the +list of processes; use the B<-bosserver> flag instead. + +=item * + +The B<-bosserver> flag stops all AFS server processes running on the +machine, including the BOS Server. A new BOS Server starts +immediately, and it starts a new instance of each process that is +marked with the Run status flag in the B file. + +=item * + +The B<-all> flag stops all AFS server processes running on the +machine, except the BOS Server, and immediately restarts the +processes that are marked with the Run status flag in the +B file. + +=back + +This command does not change a process's status flag in the B +file. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to restart each process. +Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see +the introductory reference page for the C command suite. + +=item B<-instance> I [I ...] + +Names each process to stop and then restart immediately +regardless of its status flag setting. Use the process name +assigned with the B<-instance> argument to the C command. +The output from the C command lists the names. Provide +this flag or one of the B<-bosserver> or B<-all> options, but do not +combine them. + +=item B<-bosserver> + +Stops all AFS server processes running on the machine, +including the BOS Server. A new BOS Server instance immediately +starts, and starts all processes marked with the Run status +flag in the B file. Provide this flag or one of the +B<-instance> or B<-all> options, but do not combine them. + +=item B<-all> + +Stops all AFS server processes running on the machine other +than the BOS Server, and immediately restarts the processes +marked with the B status flag in the B file. Provide +this flag or one of the B<-instance> or B<-bosserver> options, but do +not combine them. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command stops and restarts all processes running on the +machine B, including the BOS Server. + + bos restart -server fs3.abc.com -bosserver + +The following command stops and restarts all processes running on the +machine B, excluding the BOS Server. + + bos restart -server fs5.abc.com -all + +The following command stops and restarts the Protection Server and +Volume Location (VL) Server processes on the machine B: + + bos restart -server db3.abc.com -instance ptserver vlserver + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_salvage.pod b/doc/man-pages/pod/bos_salvage.pod new file mode 100644 index 0000000000..1e79497c6e --- /dev/null +++ b/doc/man-pages/pod/bos_salvage.pod @@ -0,0 +1,354 @@ +=head1 NAME + +bos salvage - Restores internal consistency to a file system or volume + +=head1 SYNOPSIS + +bos salvage B<-server> I [B<-partition> I] +[B<-volume> I] +[B<-file> I] [B<-all>] [B<-showlog>] +[B<-parallel> I<# of max parallel partition salvaging>] +[B<-tmpdir> I] +[B<-orphans> I] +[B<-cell> I] +[B<-noauth>] [B<-localauth>] [B<-help>] + +bos sa B<-se> I [B<-part> I] +[B<-v> I] +[B<-f> I] [B<-a>] [B<-sh>] +[B<-para> I<# of max parallel partition salvaging>] +[B<-t> I] +[B<-o> I] +[B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command salvages (restores internal consistency to) +one or more volumes on the file server machine named by the B<-server> +argument. When processing one or more partitions, the command restores +consistency to corrupted read/write volumes where possible. For +read-only or backup volumes, it inspects only the volume header: + +=over + +=item * + +If the volume header is corrupted, the Salvager removes the volume +completely and records the removal in its log file, +B. Issue the C or C +command to create the read-only or backup volume again. + +=item * + +If the volume header is intact, the Salvager skips the volume +(does not check for corruption in the contents). However, if the +File Server notices corruption as it initializes, it sometimes +refuses to attach the volume or bring it online. In this case, it +is simplest to remove the volume by issuing the C or C command. Then issue the C or C command to +create it again. + +=back + +Use the indicated arguments to salvage a specific number of volumes: + +=over + +=item * + +To process all volumes on a file server machine, provide the +B<-server> argument and the B<-all> flag. No volumes on the machine are +accessible to Cache Managers during the salvage operation, because +the BOS Server stops the File Server and Volume Server processes +while the Salvager runs. The BOS Server automatically restarts +them when the operation completes. + +=item * + +To process all volumes on one partition, provide the B<-server> and +B<-partition> arguments. As for a salvage of the entire machine, no +volumes on the machine are accessible to Cache Managers during the +salvage operation. The BOS Server automatically restarts the File +Server and Volume Server when the operation completes. + +=item * + +To salvage only one read/write volume, combine the B<-server>, +B<-partition>, and B<-volume> arguments. Only that volume is +inaccessible to Cache Managers, because the BOS Server does not +shutdown the File Server and Volume Server processes during the +salvage of a single volume. Do not name a read-only or backup +volume with the B<-volume> argument. Instead, remove the volume, +using the C or C command. Then create a new copy of +the volume with the C or C command. + +=back + +During the salvage of an entire machine or partition, the C +command reports the fs process's auxiliary status as C. + +The Salvager always writes a trace to the B +file on the file server machine where it runs. To record the trace in +another file as well (either in AFS or on the local disk of the +machine where the C command is issued), name the file with +the B<-file> argument. To display the trace on the standard output stream +as it is written to the B file, include the +B<-showlog> flag. + +By default, multiple Salvager subprocesses run in parallel: one for +each partition up to four, and four subprocesses for four or more +partitions. To increase or decrease the number of subprocesses running +in parallel, provide a positive integer value for the B<-parallel> +argument. + +If there is more than one server partition on a physical disk, the +Salvager by default salvages them serially to avoid the inefficiency +of constantly moving the disk head from one partition to another. +However, this strategy is often not ideal if the partitions are +configured as logical volumes that span multiple disks. To force the +Salvager to salvage logical volumes in parallel, provide the string +all as the value for the B<-parallel> argument. Provide a positive +integer to specify the number of subprocesses to run in parallel (for +example, B<-parallel 5all> for five subprocesses), or omit the integer to +run up to four subprocesses, depending on the number of logical +volumes being salvaged. + +The Salvager creates temporary files as it runs, by default writing +them to the partition it is salvaging. The number of files can be +quite large, and if the partition is too full to accommodate them, the +Salvager terminates without completing the salvage operation (it +always removes the temporary files before exiting). Other Salvager +subprocesses running at the same time continue until they finish +salvaging all other partitions where there is enough disk space for +temporary files. To complete the interrupted salvage, reissue the +command against the appropriate partitions, adding the B<-tmpdir> +argument to redirect the temporary files to a local disk directory +that has enough space. + +The B<-orphans> argument controls how the Salvager handles orphaned files +and directories that it finds on server partitions it is salvaging. An +I element is completely inaccessible because it is not +referenced by the vnode of any directory that can act as its parent +(is higher in the filespace). Orphaned objects occupy space on the +server partition, but do not count against the volume's quota. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the file server machine on which to salvage volumes. +Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see +the introductory reference page for the C command suite. + +=item B<-partition> I + +Specifies a single partition on which to salvage all volumes. +Provide the complete partition name (for example B) or +one of the following abbreviated forms: + + /vicepa = vicepa = a = 0 + /vicepb = vicepb = b = 1 + +After B (for which the index is 25) comes + + /vicepaa = vicepaa = aa = 26 + /vicepab = vicepab = ab = 27 + +and so on through + + /vicepiv = vicepiv = iv = 255 + +=item B<-volume> I + +Specifies the name or volume ID number of a read/write volume +to salvage. The B<-partition> argument must be provided along with +this one. + +=item B<-file> I + +Specifies the complete pathname of a file into which to write a +trace of the salvage operation, in addition to the +B file on the server machine. If the +file pathname is local, the trace is written to the specified +file on the local disk of the machine where the C +command is issued. If the B<-volume> argument is included, the +file can be in AFS, though not in the volume being salvaged. Do +not combine this argument with the B<-showlog> flag. + +=item B<-all> + +Salvages all volumes on all of the partitions on the machine +named by the B<-server> argument. + +=item B<-showlog> + +Displays the trace of the salvage operation on the standard +output stream, as well as writing it to the +B file. Do not combine this flag with +the B<-file> argument. + +=item B<-parallel> I<# of max parallel partition salvaging> + +Specifies the maximum number of Salvager subprocesses to run in +parallel. Provide one of three values: + +=over + +=item * + +An integer from the range B<1> to B<32>. A value of B<1> means that a +single Salvager process salvages the partitions sequentially. + +=item * + +The string C to run up to four Salvager subprocesses in +parallel on partitions formatted as logical volumes that span +multiple physical disks. Use this value only with such +logical volumes. + +=item * + +The string C followed immediately (with no intervening +space) by an integer from the range B<1> to B<32>, to run the +specified number of Salvager subprocesses in parallel on +partitions formatted as logical volumes. Use this value only +with such logical volumes. + +=back + +The BOS Server never starts more Salvager subprocesses than +there are partitions, and always starts only one process to +salvage a single volume. If this argument is omitted, up to +four Salvager subprocesses run in parallel. + +=item B<-tmpdir> I + +Specifies the full pathname of a local disk directory to which +the Salvager process writes temporary files as it runs. If this +argument is omitted, or specifies an ineligible or nonexistent +directory, the Salvager process writes the files to the +partition it is currently salvaging. + +=item B<-orphans> I + +Controls how the Salvager handles orphaned files and +directories. Choose one of the following three values: + +=over + +=item B + +Leaves the orphaned objects on the disk, but prints a +message to the B file reporting +how many orphans were found and the approximate number of +kilobytes they are consuming. This is the default if the +B<-orphans> argument is omitted. + +=item B + +Removes the orphaned objects, and prints a message to the +B file reporting how many orphans +were removed and the approximate number of kilobytes they +were consuming. + +=item B + +Attaches the orphaned objects by creating a reference to +them in the vnode of the volume's root directory. Since +each object's actual name is now lost, the Salvager +assigns each one a name of the following form: + +B<_ _ORPHANFILE_ _.>I for files + +B<_ _ORPHANDIR_ _.>I for directories + +where I is a two-digit number that uniquely +identifies each object. The orphans are charged against +the volume's quota and appear in the output of the C +command issued against the volume's root directory. + +=back + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command salvages all volumes on the B partition of +the machine B: + + bos salvage -server db3.abc.com -partition /vicepd + +The following command salvages the volume with volume ID number +536870988 on partition B of the machine B: + + bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988 + +The following command salvages all volumes on the machine B. +Six Salvager processes run in parallel rather than the default four. + + bos salvage -server fs4.abc.com -all -parallel 6 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Running this command can result in data loss if the Salvager process +can repair corruption only by removing the offending data. Consult the +IBM AFS Administration Guide for more information. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +IBM AFS Administration Guide + +=cut diff --git a/doc/man-pages/pod/bos_setauth.pod b/doc/man-pages/pod/bos_setauth.pod new file mode 100644 index 0000000000..81c442ff3a --- /dev/null +++ b/doc/man-pages/pod/bos_setauth.pod @@ -0,0 +1,114 @@ +=head1 NAME + +bos setauth - Sets authorization checking requirements for all server processes + +=head1 SYNOPSIS + +bos setauth B<-server> I +B<-authrequired> I +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos seta B<-s> I +B<-a> I +[B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command enables or disables authorization checking on +the server machine named by the B<-server> argument. When authorization +checking is enabled (the normal case), the AFS server processes +running on the machine verify that the issuer of a command meets its +privilege requirements. When authorization checking is disabled, +server processes perform any action for anyone, including the +unprivileged user B; this security exposure precludes +disabling of authorization checking except during installation or +emergencies. + +To indicate to the server processes that authorization checking is +disabled, the BOS Server creates the zero-length file +B on its local disk. All AFS server processes +constantly monitor for the B file's presence and do not check for +authorization when it is present. The BOS Server removes the file when +this command is used to reenable authorization checking. + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to enable or disable +authorization checking. Identify the machine by IP address or +its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +=item B<-authrequired> I + +Enables authorization checking if the value is C, or disables +it if the value is C. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example disables authorization checking on the machine +B: + + bos setauth -server fs7.abc.com -authrequired off + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser B if the B<-localauth> flag is +included. + +=head1 CAVEATS + +Do not create the B file directly, except when directed by +instructions for dealing with emergencies (doing so requires being +logged in as the local superuser B). Use this command instead. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/bos_setcellname.pod b/doc/man-pages/pod/bos_setcellname.pod new file mode 100644 index 0000000000..bd988ae3a6 --- /dev/null +++ b/doc/man-pages/pod/bos_setcellname.pod @@ -0,0 +1,134 @@ +=head1 NAME + +bos setcellname - Sets the cell's name in the B and +B files + +=head1 SYNOPSIS + +bos setcellname B<-server> I B<-name> I +[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] + +bos setc B<-s> I B<-n> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] + +=head1 DESCRIPTION + +The C command establishes the cell's name and makes the +server machine named by the B<-server> argument a member of it, by +recording the value of the B<-name> argument in two files which it +creates on the local disk: + +=over + +=item * + +B + +=item * + +B. The cell name appears on the first line +in the file, preceded by the required > symbol. The machine name +specified with the B<-server> argument appears on the second line +along with its IP address as obtained from the cell's naming +service. The machine is thus designated as the cell's first +database server machine. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-server> I + +Indicates the server machine on which to set the cell name in +the B and B file. It is always the first +machine installed in a cell. Identify the machine by IP address +or its host name (either fully-qualified or abbreviated +unambiguously). For details, see the introductory reference +page for the C command suite. + +=item B<-name> I + +Defines the cell name, using standard Internet domain name +format (the actual domain name is usually appropriate). +Examples are B for the ABC Corporation and B for +the State University. It must match the value of the B<-cell> +argument, if that is provided. + +=item B<-cell> I + +Names the cell in which to run the command. Do not combine this +argument with the B<-localauth> flag. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. Do +not combine this flag with the B<-localauth> flag. For more +details, see the introductory L reference page. + +=item B<-localauth> + +Constructs a server ticket using a key from the local +B file. The C command interpreter presents +the ticket to the BOS Server during mutual authentication. Do +not combine this flag with the B<-cell> or B<-noauth> options. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command defines the cell name B in the B +and B files on the machine B as it is installed as +the cell's first server machine. + + bos setcellname -server fs1.abc.com -name abc.com + +=head1 PRIVILEGE REQUIRED + +Authorization checking is normally turned off during installation, +which is the only recommended time to use this command; in this case +no privilege is required. If authorization checking is turned on, the +issuer must be listed in the B file on the machine +named by the B<-server> argument, or must be logged in as the local +superuser B if the B<-localauth> flag is included. + +=head1 CAVEATS + +Issue this command only when the installing the cell's first AFS +server machine. The IBM AFS Quick Beginnings explains how to copy over +the B and B files from this or another appropriate +machine during installation of additional server machines. + +Be sure to choose a satisfactory cell name when issuing this command, +because changing a cell's name is very complicated; for one thing, it +requires changing every password in the Authentication Database. +Consult the IBM AFS Administration Guide for advice on choosing a cell +name. If changing the cell's name is absolutely necessary, contact AFS +Product Support for complete instructions. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +IBM AFS Quick Beginnings, +IBM AFS Administration Guide + +=cut diff --git a/doc/man-pages/pod/bos_setrestart.pod b/doc/man-pages/pod/bos_setrestart.pod new file mode 100644 index 0000000000..673433e7ae --- /dev/null +++ b/doc/man-pages/pod/bos_setrestart.pod @@ -0,0 +1,190 @@ +=head1 NAME + +bos setrestart - Sets the date and time at which the BOS Server restarts processes + +=head1 SYNOPSIS + +bos setrestart B<-server> I B<-time> I (for B) and press BReturnE> at the Tape Coordinator's +prompt for the first tape. + +Tape Coordinator operation depends on the correct configuration of +certain files, as described in the following list: + +=over + +=item * + +The local B file must include an entry +for the Tape Coordinator that specifies its device name and port +offset number, among other information; for details, see the +L reference page. + +=item * + +The port offset number recorded in the Tape Coordinator's entry in +the Backup Database must match the one in the B file. +Create the Backup Database entry by using the C +command. + +=item * + +The optional BI file can contain +instructions for mounting and unmounting tapes automatically (when +using a tape stacker or jukebox, for instance) or automating other +aspects of the backup process. The I part of the name is +derived as described previously for the BI and +BI files. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-port> I + +Specifies the port offset number of the Tape Coordinator to +initialize. + +=item B<-debuglevel> I<0> | I<1> | I<2> + +Controls the amount and type of messages the Tape Coordinator +displays on the standard output stream. Provide one of three +acceptable values: + +=over + +=item * + +B<0> to display the minimum level of detail required to describe +Tape Coordinator operations, including prompts for tapes, +messages that indicate the beginning and end of operations, +and error messages. This is the default value. + +=item * + +B<1> to display the names of the volumes being dumped or +restored as well as the information displayed at level 0. + +=item * + +B<2> to display all messages also being written to the +BI log file. + +=back + +=item B<-cell> I + +Names the cell in which the Tape Coordinator operates (the cell +to which the file server machines that house affected volumes +belong). If this argument is omitted, the Tape Coordinator runs +in the local cell as defined in the local +B file. Do not combine this flag with the +B<-localauth> argument. + +=item B<-noautoquery> + +Suppresses the Tape Coordinator's prompt for insertion of the +first tape needed for an operation. The operator must insert +the tape into the drive before issuing the C command that +initializes the operation. + +=item B<-localauth> + +Constructs a server ticket using the server encryption key with +the highest key version number in the local +B. The C command interpreter presents the +ticket, which never expires, to the Volume Server and Volume +Location Server to use in mutual authentication. + +Do not combine this argument with the B<-cell> flag, and use it +only when logged on to a server machine as the local superuser +B; client machines do not have B file. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command starts the Tape Coordinator with port offset B<7> +at debug level B<1>, meaning the Tape Coordinator reports the names of +volumes it is dumping or restoring. + + butc -port 7 -debuglevel 1 + +=head1 PRIVILEGE REQUIRED + +The issuer must be listed in the B file on every +machine where the Backup Server or Volume Location (VL) Server is +running, and on every file server machine that houses a volume to be +backed up. If the B<-localauth> flag is included, the issuer must instead +be logged on to the Tape Coordinator machine as the local superuser +B. In addition, the issuer must be able to read and write to the +log and configuration files in the local B directory. + +=head1 CAVEATS + +If the Tape Coordinator machine is an AIX machine, use the B +utility to set the device's block size to 0 (zero), indicating +variable block size. Otherwise, tape devices attached to machines +running other operating systems sometimes cannot read tapes written on +AIX machines. For instructions, see the IBM AFS Administration Guide +chapter about configuring the Backup System. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/dlog.pod b/doc/man-pages/pod/dlog.pod new file mode 100644 index 0000000000..c99d747db5 --- /dev/null +++ b/doc/man-pages/pod/dlog.pod @@ -0,0 +1,230 @@ +=head1 NAME + +dlog - Authenticates to the DCE Security Service + +=head1 SYNOPSIS + +dlog [B<-principal> I] [B<-cell> I] +[B<-password> I] [B<-servers> I [I ...]] +[B<-lifetime> I] +[B<-setpag>] [B<-pipe>] [B<-help>] + +dlog [B<-pr> I] [B<-c> I] [B<-pw> I] +[B<-ser> I [I ...]] +[B<-l> I] [B<-set>] [B<-pi>] [B<-h>] + +=head1 DESCRIPTION + +The C command obtains DCE credentials for the issuer from the DCE +Security Service in the cell named by the B<-cell> argument, and stores +them on the AFS client machine on which the user issues the command. +The AFS/DFS Migration Toolkit Protocol Translator processes running on +machines in the DCE cell accept the credentials, which enables the +user to access the DCE cell's filespace from the AFS client. The +user's identity in the local file system is unchanged. + +If the issuer does not provide the B<-principal> argument, the C +command interpreter uses the user name under which the issuer is +logged into the local file system. Provide the DCE password for the +appropriate user name. As with the C command, the password does not +cross the network in clear text (unless the issuer is logged into the +AFS client from a remote machine). + +The credentials are valid for a lifetime equivalent to the smallest of +the following, all but the last of which is defined by the DCE cell's +Security Server: + +=over + +=item * + +The maximum certificate lifetime for the issuer's DCE account + +=item * + +The maximum certificate lifetime for the B principal's DCE +account + +=item * + +The registry-wide maximum certificate lifetime + +=item * + +The registry-wide default certificate lifetime + +=item * + +The lifetime requested using the B<-lifetime> argument + +=back + +If the previous maximum certificate lifetime values are set to +B, the maximum possible ticket lifetime is defined by the +default certificate lifetime. Refer to the DCE vendor's administration +guide for more information before setting any of these values. + +The AFS Cache Manager stores the ticket in a credential structure +associated with the name of the issuer (or the user named by the +B<-principal> argument. If the user already has a ticket for the DCE +cell, the ticket resulting from this command replaces it in the +credential structure. + +The AFS C command displays the ticket obtained by the C +command for the server principal B, regardless of the principal to +which it is actually granted. Note that the tokens command does not +distinguish tickets for a DFS(TM) File Server from tickets for an AFS +File Server. + +=head1 OPTIONS + +=over 4 + +=item B<-principal> I + +Specifies the DCE user name for which to obtain DCE +credentials. If this option is omitted, the C command +interpreter uses the name under which the issuer is logged into +the local file system. + +=item B<-cell> I + +Specifies the DCE cell in which to authenticate. During a +single login session on a given machine, a user can +authenticate in multiple cells simultaneously, but can have +only one ticket at a time for each cell (that is, it is +possible to authenticate under only one identity per cell per +machine). It is legal to abbreviate the cell name to the +shortest form that distinguishes it from the other cells listed +in the B file on the local client +machine. + +If the issuer does not provide the B<-cell> argument, the C +command attempts to authenticate with the DCE Security Server +for the cell defined by + +=over + +=item 1. + +The value of the environment variable AFSCELL on the local +AFS client machine, if defined. The issuer can set the +AFSCELL environment variable to name the desired DCE cell. + +=item 2. + +The cell name in the B file on the local +AFS client machine. The machine's administrator can place the +desired DCE cell's name in the file. + +=back + +=item B<-password> I + +Specifies the password for the issuer (or for the user named by +the B<-principal> argument). Using this argument is not +recommended, because it makes the password visible on the +command line. If this argument is omitted, the command prompts +for the password and does not echo it visibly. + +=item B<-servers> I ... + +Specifies a list of DFS database server machines running the +Translator Server through which the AFS client machine can +attempt to authenticate. Specify each server by hostname, +shortened machine name, or IP address. If this argument is +omitted, the C command interpreter randomly selects a +machine from the list of DFS Fileset Location (FL) Servers in +the B file for the DCE cell specified by +the B<-cell> argument. This argument is useful for testing when +authentication seems to be failing on certain server machines. + +=item B<-lifetime> I + +Requests a ticket lifetime using the format I:I[:I] (hours, +minutes, and optionally a number seconds between 00 and 59). +For example, the value B<168:30> requests a ticket lifetime of 7 +days and 30 minutes, and B<96:00> requests a lifetime of 4 days. +Acceptable values range from B<00:05> (5 minutes) to B<720:00> (30 +days). If this argument is not provided and no other +determinants of ticket lifetime have been changed from their +defaults, ticket lifetime is 10 hours. + +The requested lifetime must be smaller than any of the DCE +cell's determinants for ticket lifetime; see the discussion in +the preceding L section. + +=item B<-setpag> + +Creates a process authentication group (PAG) in which the newly +created ticket is placed. If this flag is omitted, the ticket +is instead associated with the issuers' local user ID (UID). + +=item B<-pipe> + +Suppresses any prompts that the command interpreter otherwise +produces, including the prompt for the issuer's password. +Instead, the command interpreter accepts the password via the +standard input stream. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the C command interpreter cannot contact a Translator Server, it +produces a message similar to the following: + + dlog: server or network not responding -- failed to contact + authentication service + +=head1 EXAMPLES + +The following command authenticates the issuer as B in the +B cell. + + dlog -principal cell_admin -cell dce.abc.com + Password: cell_admin's password + +In the following example, the issuer authenticates as B to +the B cell and request a ticket lifetime of 100 hours. The +C command confirms that the user obtained DCE credentials as the +user B: the AFS ID is equivalent to the UNIX ID of B<1> assigned +to B in B cell's DCE registry. + + dlog -principal cell_admin -cell dce.abc.com -lifetime 100 + Password: cell_admin's password + + + tokens + Tokens held by the Cache Manager: + + User's (AFS ID 1) tokens for afs@dce.abc.com [Expires Jul 6 14:12] + User's (AFS ID 4758) tokens for afs@abc.com [Expires Jul 2 13:14] + + --End of list-- + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/dpass.pod b/doc/man-pages/pod/dpass.pod new file mode 100644 index 0000000000..74fe47f7f3 --- /dev/null +++ b/doc/man-pages/pod/dpass.pod @@ -0,0 +1,113 @@ +=head1 NAME + +dpass - Returns the DCE password for a new DCE account + +=head1 SYNOPSIS + +dpass [B<-cell> I] [B<-help>] + +dpass [B<-c> I] [B<-h>] + +=head1 DESCRIPTION + +The C command returns the DCE password that an administrator +assigned to the issuer when using the C command to migrate AFS +user accounts into a DCE cell. + +The C command, issued on an AFS client, requests the issuer's new +DCE password from the AFS cell specified with the B<-cell> argument. + +The issuer must be authenticated as the AFS user whose AFS account was +moved into DCE, and be able to provide the user's AFS password when +prompted by the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-cell> I + +Specifies the name of the AFS cell from which the AFS account +was moved into DCE and from which to fetch the new DCE +password. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +By default, the C command writes a message similar to the +following to the standard output stream. + + Please read the following message before entering your password. + + This program will display your new, temporary DCE password on your + terminal, and you should change the assigned password as soon as + possible (from a DCE client). The program assumes that the AFS cell + uses the AFS Authentication Server and that an administrator used the + utilities in the AFS/DFS Migration Toolkit to migrate the account from + AFS to DCE. The password you enter should be the AFS password that was + in effect when your DCE account was created; this is not necessarily + the same password you have at the moment. The cell name (which you + may override with a command line option), must be the name of the AFS + cell from which the authentication information was taken. + +To suppress this message, set the DPASS_NO_MESSAGE environment +variable. It is then possible to substitute a customized message if +desired by using a script similar to the following example: + + #! B + echo "Start of customized message" + echo "Continuation of customized message" + . + . + . + echo "Conclusion of customized message" + setenv DPASS_NO_MESSAGE + dpass $* + +After the standard or customized message, if any, the C command +generates the following prompt for the original AFS password: + + Original password for AFS cell cell: + Re-enter password to verify: + +If the AFS passwords match and are correct, the command reports the +temporary DCE password in the following message. + + The new DCE password is: Issuer's_temporary_DCE_password + +=head1 EXAMPLES + +The following example returns the DCE password of the issuer, whose +AFS account is in the B cell. The DPASS_NO_MESSAGE variable has +been set to suppress the standard message. + + dpass + Original password for AFS cell abc.com: Issuer's_AFS_password + Re-enter password to verify: Issuer's_AFS_password + The new DCE password is: 8655--eg8e-dcdc-8157 + +=head1 PRIVILEGE REQUIRED + +The issuer must be authenticated as the AFS user for whom to display +the corresponding DCE password. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +C reference page in IBM AFS/DFS Migration Toolkit Administration Guide and Reference + +=cut diff --git a/doc/man-pages/pod/fileserver.pod b/doc/man-pages/pod/fileserver.pod new file mode 100644 index 0000000000..88b7939020 --- /dev/null +++ b/doc/man-pages/pod/fileserver.pod @@ -0,0 +1,493 @@ +=head1 NAME + +fileserver - Initializes the File Server component of the fs process + +=head1 SYNOPSIS + +fileserver [B<-d> I] [B<-p> I] +[B<-spare> I] +[B<-pctspare> I] [B<-b> I] +[B<-l> I] [B<-s> I] +[B<-vc> I] [B<-w> I] +[B<-cb> I] +[B<-banner> (print banner every 10 minutes)] +[B<-novbc> (whole volume cbs disabled)] +[B<-implicit> I] +[B<-hr> I] +[B<-busyat> I n>] +[B<-rxpck> I] +[B<-rxdbg> (enable rx debugging)] +[B<-rxdbge> (enable rxevent debugging)] +[B<-m> I] +[B<-lock> (keep fileserver from swapping)] +[B<-L> (large server conf)] [B<-S> (small server conf)] +[B<-k> I] [B<-realm> I] +[B<-udpsize> I] +[B<-enable_peer_stats>] [B<-enable_process_stats>] +[B<-help>] + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + +=head1 DESCRIPTION + +The C command initializes the File Server component of the B +process. In the conventional configuration, its binary file is located +in the B directory on a file server machine. + +The C command is not normally issued at the command shell +prompt, but rather placed into a database server machine's +B file with the C command. If it is +ever issued at the command shell prompt, the issuer must be logged +onto a file server machine as the local superuser B. + +The File Server creates the B log file as it +initializes, if the file does not already exist. It does not write a +detailed trace by default, but use the B<-d> option to increase the +amount of detail. Use the C command to display the contents +of the log file. + +The command's arguments enable the administrator to control many +aspects of the File Server's performance, as detailed in the L +section. By default the C command sets values for many +arguments that are suitable for a medium-sized file server machine. To +set values suitable for a small or large file server machine, use the +B<-S> or B<-L> flag respectively. The following list describes the +parameters and corresponding argument for which the C command +sets default values, and L summarizes the setting for each of +the three machine sizes. + +=over + +=item * + +The maximum number of lightweight processes (LWPs) the File Server +uses to handle requests for data; corresponds to the B<-p> argument. +The File Server always uses a minimum of 32 KB for these +processes. + +=item * + +The maximum number of directory blocks the File Server caches in +memory; corresponds to the B<-b> argument. Each cached directory +block (buffer) consumes 2,092 bytes of memory. + +=item * + +The maximum number of large vnodes the File Server caches in +memory for tracking directory elements; corresponds to the B<-l> +argument. Each large vnode consumes 292 bytes of memory. + +=item * + +The maximum number of small vnodes the File Server caches in +memory for tracking file elements; corresponds to the B<-s> argument. +Each small vnode consumes 100 bytes of memory. + +=item * + +The maximum volume cache size, which determines how many volumes +the File Server can cache in memory before having to retrieve data +from disk; corresponds to the B<-vc> argument. + +=item * + +The maximum number of callback structures the File Server caches +in memory; corresponds to the B<-cb> argument. Each callback +structure consumes 16 bytes of memory. + +=item * + +The maximum number of B packets the File Server uses; corresponds +to the B<-rxpck> argument. Each packet consumes 1544 bytes of memory. + +=back + +=head2 Table 1 + +B + + ------------------------------------------------- + Parameter | Configuration: + (Argument) | Small | Medium | Large + | (-S) | (default) | (-L) + ------------------------------------------------- + Number of | 6 | 9 | 12 + LWPs (-p) | | | + ------------------------------------------------- + Number of cached | 70 | 90 | 120 + directory blocks | | | + (-b) | | | + ------------------------------------------------- + Number of cached | 200 | 400 | 600 + large vnodes (-l) | | | + ------------------------------------------------- + Number of cached | 200 | 400 | 600 + small vnodes (-s) | | | + ------------------------------------------------- + Maximum volume | 200 | 400 | 600 + cache size (-vc) | | | + ------------------------------------------------- + Number of | 20,000 | 60,000 | 64,000 + callbacks (-cb) | | | + ------------------------------------------------- + Number of Rx | 100 | 150 | 200 + packets (-rxpck) | | | + ------------------------------------------------- + +To override any of the values, provide the indicated argument (which +can be combined with the B<-S> or B<-L> flag). + +The amount of memory required for the File Server varies. The +approximate default memory usage is 751 KB when the B<-S> flag is used +(small configuration), 1.1 MB when all defaults are used (medium +configuration), and 1.4 MB when the B<-L> flag is used (large +configuration). If additional memory is available, increasing the +value of the B<-cb> and B<-vc> arguments can improve File Server performance +most directly. + +By default, the File Server allows a volume to exceed its quota by 1 +MB when an application is writing data to an existing file in a volume +that is full. The File Server still does not allow users to create new +files in a full volume. To change the default, use one of the +following arguments: + +=over + +=item * + +Set the B<-spare> argument to the number of extra kilobytes that the +File Server allows as overage. A value of B<0> allows no overage. + +=item * + +Set the B<-pctspare> argument to the percentage of the volume's quota +the File Server allows as overage. + +=back + +By default, the File Server implicitly grants the B (B) and B +(B) permissions to the B on the access +control list (ACL) of every directory in the volumes stored on its +file server machine. In other words, the group's members can exercise +those two permissions even when an entry for the group does not appear +on an ACL. To change the set of default permissions, use the B<-implicit> +argument. + +The File Server maintains a I (I) for each client machine from which it has received a data access +request. Like the CPS for a user, a host CPS lists all of the +Protection Database groups to which the machine belongs, and the File +Server compares the host CPS to a directory's ACL to determine in what +manner users on the machine are authorized to access the directory's +contents. When the C or C command is used to +change the groups to which a machine belongs, the File Server must +recompute the machine's host CPS in order to notice the change. By +default, the File Server contacts the Protection Server every two +hours to recompute host CPSs, implying that it can take that long for +changed group memberships to become effective. To change this +frequency, use the B<-hr> argument. + +=over + +=item B + +The AIX operating system does not automatically reserve a part +of each partition to avoid the negative consequences that can result +when the space on a partition is completely exhausted. Therefore, the +AIX version of the File Server creates an 8% disk reserve +automatically. To change the percentage, use the B<-m> argument. + +=back + +The File Server generates the following message when a partition is +nearly full: + + No space left on device + +=head1 OPTIONS + +=over 4 + +=item B<-d> I + +Sets the detail level for the debugging trace written to the +B file. Provide one of the following +values, each of which produces an increasingly detailed trace: +B<0>, B<1>, B<5>, B<25>, and B<125>. The default value of B<0> produces only a +few messages. + +=item B<-p> I + +Sets the number of threads to run. Provide a positive integer. +The File Server creates and uses five threads for special +purposes, in addition to the number specified (but if this +argument specifies the maximum possible number, the File Server +automatically uses five of the threads for its own purposes). + +The maximum number of threads can differ in each release of +AFS. Consult the IBM AFS Release Notes for the current release. + +=item B<-spare> I + +Specifies the number of additional kilobytes an application can +store in a volume after the quota is exceeded. Provide a +positive integer; a value of B<0> prevents the volume from ever +exceeding its quota. Do not combine this argument with the +B<-pctspare> argument. + +=item B<-pctspare> I + +Specifies the amount by which the File Server allows a volume +to exceed its quota, as a percentage of the quota. Provide an +integer between B<0> and B<99>. A value of B<0> prevents the volume from +ever exceeding its quota. Do not combine this argument with the +B<-spare> argument. + +=item B<-b> I + +Sets the number of directory buffers. Provide a positive +integer. + +=item B<-l> I + +Sets the number of large vnodes available in memory for caching +directory elements. Provide a positive integer. + +=item B<-s> I + +Sets the number of small vnodes available in memory for caching +file elements. Provide a positive integer. + +=item B<-vc> I + +Sets the number of volumes the File Server can cache in memory. +Provide a positive integer. + +=item B<-w> I + +Sets the interval at which the daemon spawned by the File +Server performs its maintenance tasks. Do not use this +argument; changing the default value can cause unpredictable +behavior. + +=item B<-cb> I + +Sets the number of callbacks the File Server can track. Provide +a positive integer. + +=item B<-banner> + +Prints the following banner to B about every 10 +minutes. + +File Server is running at I permission to the +B group, even if you use the B value. + +=back + +=item B<-hr> I + +Specifies how often the File Server refreshes its knowledge of +the machines that belong to protection groups (refreshes the +host CPSs for machines). The File Server must update this +information to enable users from machines recently added to +protection groups to access data for which those machines now +have the necessary ACL permissions. + +=item B<-busyat> I + +Defines the number of incoming RPCs that can be waiting for a +response from the File Server before the File Server returns +the error code B to the Cache Manager that sent the latest +RPC. In response, the Cache Manager retransmits the RPC after a +delay. This argument prevents the accumulation of so many +waiting RPCs that the File Server can never process them all. +Provide a positive integer. The default value is 600. + +=item B<-rxpck> I + +Controls the number of Rx packets the File Server uses to store +data for incoming RPCs that it is currently handling, that are +waiting for a response, and for replies that are not yet +complete. Provide a positive integer. + +=item B<-rxdbg> + +Writes a trace of the File Server's operations on Rx packets to +the file B. + +=item B<-rxdbge> + +Writes a trace of the File Server's operations on Rx events +(such as retransmissions) to the file B. + +=item B<-m> I + +Specifies the percentage of each AFS server partition that the +AIX version of the File Server creates as a reserve. Specify an +integer value between B<0> and B<30>; the default is 8%. A value of B<0> +means that the partition can become completely full, which can +have serious negative consequences. + +=over + +=item B + +This argument is available only on machines running the AIX +operating system, and so does not appear in the syntax statement when +the B<-help> flag is used on other system types. + +=back + +=item B<-lock> + +Prevents any portion of the B binary from being paged +(swapped) out of memory on a file server machine running the +IRIX operating system. + +=over + +=item B + +This argument is available only on machines running the IRIX +operating system, and so does not appear in the syntax statement when +the B<-help> flag is used on other system types. + +=back + +=item B<-L> + +Sets values for many arguments in a manner suitable for a large +file server machine. Combine this flag with any option except +the B<-S> flag; omit both flags to set values suitable for a +medium-sized file server machine. + +=item B<-S> + +Sets values for many arguments in a manner suitable for a small +file server machine. Combine this flag with any option except +the B<-L> flag; omit both flags to set values suitable for a +medium-sized file server machine. + +=item B<-k> I + +Sets the LWP stack size in units of 1 kilobyte. Do not use this +argument, and in particular do not specify a value less than +the default of 24. + +=item B<-realm> I + +Defines the Kerberos realm name for the File Server to use. If +this argument is not provided, it uses the realm name +corresponding to the cell listed in the local +B file. + +=item B<-udpsize> I + +Sets the size of the UDP buffer, which is 64 KB by default. +Provide a positive integer, preferably larger than the default. + +=item B<-enable_peer_stats> + +Activates the collection of Rx statistics and allocates memory +for their storage. For each connection with a specific UDP port +on another machine, a separate record is kept for each type of +RPC (FetchFile, GetStatus, and so on) sent or received. To +display or otherwise access the records, use the Rx Monitoring +API. + +=item B<-enable_process_stats> + +Activates the collection of Rx statistics and allocates memory +for their storage. A separate record is kept for each type of +RPC (FetchFile, GetStatus, and so on) sent or received, +aggregated over all connections to other machines. To display +or otherwise access the records, use the Rx Monitoring API. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following C command creates an B process on the file +server machine B that uses the large configuration size, and +allows volumes to exceed their quota by 10%. Type the command on a +single line: + + bos create -server fs2.abc.com -instance fs -type fs \ + -cmd "/usr/afs/bin/fileserver -pctspare 10 \ + -L" /usr/afs/bin/volserver /usr/afs/bin/salvager + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the superuser B on a file server +machine to issue the command at a command shell prompt. It is +conventional instead to create and start the process by issuing the +C command. + +=head1 CAVEATS + +Do not use the B<-k> and B<-w> arguments, which are intended for use by the +AFS Development group only. Changing them from their default values +can result in unpredictable File Server behavior. In any case, on many +operating systems the File Server uses native threads rather than the +LWP threads, so using the B<-k> argument to set the number of LWP threads +has no effect. + +Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so +causes the File Server to exit, leaving an error message in the +B file. + +Options that are available only on some system types, such as the B<-m> +and B<-lock> options, appear in the output generated by the B<-help> option +only on the relevant system type. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fms.pod b/doc/man-pages/pod/fms.pod new file mode 100644 index 0000000000..1a7cc9bb40 --- /dev/null +++ b/doc/man-pages/pod/fms.pod @@ -0,0 +1,145 @@ +=head1 NAME + +fms - Determine a tape's capacity and a tape device's filemark size + +=head1 SYNOPSIS + +fms B<-tape> I [B<-help>] + +fms B<-t> I [B<-h>] + +=head1 DESCRIPTION + +The C command determines the capacity of the tape currently in the +tape device identified by the B<-tape> argument, along with the size of +the filemark for the device. The filemark is also referred to as the +device's end-of-file (EOF) marker, and can differ for each combination +of tape and tape device. + +As the Tape Coordinator writes a dump, it writes a filemark between +the data included from each volume and also tracks the amount of space +left before the end of the tape (EOT). For some tape devices, the +filemark is large enough (multiple megabytes) that failure to consider +it leads the Tape Coordinator significantly to overestimate the +available space. + +The intended use of this command is to determine tape capacity and +filemark size values that can be specified in a tape device's entry in +the B file. For certain types of tape drives, +the Tape Coordinator operates more efficiently when the B +file lists accurate values. For further discussion, see the IBM AFS +Administration Guide chapter on configuring the Backup System. + +Insert a tape in the drive before issuing this command. + +=head1 OPTIONS + +=over 4 + +=item B<-tape> I + +Specifies the UNIX device name of the tape device for which to +determine filemark size and the capacity of the tape it +currently contains. The format varies on different system +types, but usually begins with B; an example is B. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The command generates output both on the standard output stream and in +the B file that it creates in the current working directory. The +output reports the capacity of the tape in the device and the device's +filemark size. + +The first few lines of output include status information about the +execution of the command, including such information as the number of +blocks and the number of file marks written to the tape by the +command. The last two lines of both screen and file output provide the +following information: + +=over + +=item * + +C I C: specifies the size, in bytes, of +the tape in the device. + +=item * + +C I C: specifies the device's filemark size +in bytes. + +=back + +The following message indicates that the C command interpreter +cannot access the tape device. The command halts. + +Can't open tape drive I + +The following message indicates that the command interpreter cannot +create the B log file. Again, the command halts. + +Can't open log file + +=head1 EXAMPLES + +The following command illustrates the output for the device called +B: + + fms /dev/rmt1h + wrote block: 130408 + Finished data capacity test - rewinding + wrote 1109 blocks, 1109 file marks + Finished file mark test + Tape capacity is 2136604672 bytes + File marks are 1910205 bytes + +The following appears in the B file: + + fms test started + wrote 9230 blocks + Finished file mark test + Tape capacity is 151224320 bytes + File marks are 2375680 bytes + +=head1 PRIVILEGE REQUIRED + +The issuer must be able to insert and write to files in the currently +working directory, if the B file does not already exist. If it +already exists, the issuer need only be able to write to it. + +=head1 CAVEATS + +Do not use this command on compressing tape devices in compression +mode or with tape devices that handle tapes of multigigabyte (or +multiterabyte) capacity. It does not produce accurate results in those +cases. For alternate suggestions on the values to record in the +B file for compressing drives, see the IBM AFS Administration +Guide chapter on configuring the Backup System. + +Running the command completely overwrites the tape, so use a blank one +or one that can be recycled. + +Because it writes filemarks to the complete length of the tape, the +command can take from several hours to more than a day to complete. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs.pod b/doc/man-pages/pod/fs.pod new file mode 100644 index 0000000000..351888c21a --- /dev/null +++ b/doc/man-pages/pod/fs.pod @@ -0,0 +1,203 @@ +=head1 NAME + +fs - Introduction to the C command suite + +=head1 DESCRIPTION + +The commands in the C command suite constitute the main +administrative interface to the Cache Manager on an AFS client +machine, which is responsible for fetching AFS data from file server +machines on behalf of applications running on the client machine. + +There are several categories of commands in the C command suite: + +=over + +=item * + +Commands to set and report how the Cache Manager interacts with +server machines: C, C, C, C, C, C, +C, C, and C + +=item * + +Commands to administer access control lists (ACLs): C, +C, C, and C + +=item * + +Commands to administer server machines, volumes or partitions that +house a given file or directory: C, C, C, C, C, C, +C, and C + +=item * + +Commands to administer the local client cache and related +information: C, C, C, C, and C + +=item * + +Commands to administer volume mount points: C, C, and C + +=item * + +Commands to control monitoring and tracing: C, and C + +=item * + +A command to administer the Cache Manager's interaction with other +file systems: C + +=item * + +Commands to obtain help: C and C + +=back + +The Cache Manager and the C commands use and maintain the following +configuration files: + +=over + +=item * + +The B file lists the database server +machines in the local cell and any foreign cell to which the +administrator wishes to enable AFS access for users working on the +machine. The database server machines run the Authentication, +Backup, Protection and Volume Location (VL) Server processes, +which maintain databases of administrative information. For users +to access a cell, its B volume must also be mounted in the +local cell's AFS file tree. + +=item * + +The B file defines the machine's cell +membership with respect to the AFS command suites and Cache +Manager access to AFS data. + +=item * + +The B file defines configuration parameters +for the cache, including its size and whether it is in memory or +on disk. + +=back + +In addition, the Cache Manager automatically creates files on the +cache partition (by default, B for caching and tracking +files fetched from file server machines. + +For more details, see the reference page for each file. + +=head1 OPTIONS + +The following flag is available on every command in the C suite. The +reference page for each command also lists it, but it is described +here in greater detail. + +=over 4 + +=item B<-help> + +Prints a command's online help message on the standard output +stream. Do not combine this flag with any of the command's +other options; when it is provided, the command interpreter +ignores all other options, and only prints the help message. + +=back + +=head1 PRIVILEGE REQUIRED + +The privileges required for C commands vary more than for other +command suites. Pay special attention to the C +section of each command description. + +The various types of necessary privilege include: + +=over + +=item * + +Having permissions on a directory's ACL. For example, creating and +removing mount points requires B (B), B (B), and B +(B) permissions on the ACL of the directory in which the +mount point resides. + +=item * + +Being logged onto the machine as the local superuser B. This is +necessary when issuing commands that affect Cache Manager +configuration. + +=item * + +Belonging to the B group in the Protection +Database. + +=item * + +No privilege. Many C commands simply list information. + +=back + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_apropos.pod b/doc/man-pages/pod/fs_apropos.pod new file mode 100644 index 0000000000..2690f2beb4 --- /dev/null +++ b/doc/man-pages/pod/fs_apropos.pod @@ -0,0 +1,71 @@ +=head1 NAME + +fs apropos - Displays each help entry containing a keyword string + +=head1 SYNOPSIS + +fs apropos B<-topic> I [B<-help>] + +fs ap B<-t> I [B<-h>] + +=head1 DESCRIPTION + +The C command displays the first line of the online help +entry for any C command that has in its name or short description the +string specified by the B<-topic> argument. + +To display the syntax for a command, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I + +Specifies the keyword string to match, in lowercase letters +only. If the string is more than a single word, surround it +with double quotes ("") or other delimiters. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of a command's online help entry names it and briefly +describes its function. This command displays the first line for any +C command where the string specified with the B<-topic> argument is part +of the command name or first line. + +=head1 EXAMPLES + +The following command lists all C commands that include the word +B in their names or short online descriptions: + + fs apropos cache + setcachesize: set cache size + flush: flush file from cache + getcacheparms: get cache usage info + monitor: set cache monitor host address + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_checkservers.pod b/doc/man-pages/pod/fs_checkservers.pod new file mode 100644 index 0000000000..c83e0ccc00 --- /dev/null +++ b/doc/man-pages/pod/fs_checkservers.pod @@ -0,0 +1,234 @@ +=head1 NAME + +fs checkservers - Displays the status of server machines + +=head1 SYNOPSIS + +fs checkservers [B<-cell> I] [B<-all>] [B<-fast>] +[B<-interval> I] [B<-help>] + +fs checks [B<-c> I] [B<-a>] [B<-f>] +[B<-i> I] [B<-h>] + +=head1 DESCRIPTION + +The C command reports whether certain AFS server +machines are accessible from the local client machine. The machines +belong to one of two classes, and the Cache Manager maintains a list +of them in kernel memory: + +=over + +=item * + +The database server machines in every cell listed in the local +B file, plus any machines added to the +memory list by the C command since the last reboot. + +=item * + +All file server machines the Cache Manager has recently contacted, +and which it probably needs to contact again soon. In most cases, +the Cache Manager holds a callback on a file or volume fetched +from the machine. + +=back + +If the Cache Manager is unable to contact the B process on a +database server machine or the B process on a file server +machine, it marks the machine as inaccessible. (Actually, if a file +server machine is multihomed, the Cache Manager attempts to contact +all of the machine's interfaces, and only marks the machine as down if +the B fails to reply via any of them.) The Cache Manager then +periodically (by default, every three minutes) sends a probe to each +marked machine, to see if it is still inaccessible. If a previously +inaccessible machine responds, the Cache Manager marks it as +accessible and no longer sends the periodic probes to it. + +The C command updates the list of inaccessible machines +by having the Cache Manager probe a specified set of them: + +=over + +=item * + +By default, only machines that are marked inaccessible and belong +to the local cell (the cell listed in the local +B file) + +=item * + +If the B<-cell> argument is included, only machines that are marked +inaccessible and belong to the specified cell + +=item * + +If the B<-all> flag is included, all machines marked inaccessible + +=back + +If the B<-fast> flag is included, the Cache Manager does not probe any +machines, but instead reports the results of the most recent previous +probe. + +To set the interval between probes rather than produce a list of +inaccessible machines, use the B<-interval> argument. The non-default +setting persists until the machine reboots; to preserve it across +reboots, put the appropriate C command in the machine's +AFS initialization files. + +=head1 OPTIONS + +=over 4 + +=item B<-cell> I + +Names each cell in which to probe server machines marked as +inaccessible. Provide the fully qualified domain name, or a +shortened form that disambiguates it from the other cells +listed in the local B file. Combine this +argument with the B<-fast> flag if desired, but not with the B<-all> +flag. Omit both this argument and the B<-all> flag to probe +machines in the local cell only. + +=item B<-all> + +Probes all machines in the Cache Manager's memory list that are +marked inaccessible. Combine this argument with the B<-fast> flag +if desired, but not with the B<-cell> argument. Omit both this +flag and the B<-cell> argument to probe machines in the local cell +only. + +=item B<-fast> + +Displays the Cache Manager's current list of machines that are +inaccessible, rather than sending new probes. The output can as +old as the current setting of the probe interval (by default +three minutes, and maximum ten minutes). + +=item B<-interval> I + +Sets or reports the number of seconds between the Cache +Manager's probes to machines in the memory list that are marked +inaccessible: + +=over + +=item * + +To set the interval, specify a value from the range between B<1> +and B<600> (10 minutes); the default is B<180> (three minutes). The +issuer must be logged in as the local superuser B. The +altered setting persists until again changed with this +command, or until the machine reboots, at which time the +setting returns to the default. + +=item * + +Provide a value of B<0> (zero) to display the current interval +setting. No privilege is required. Do not combine this +argument with any other. + +=back + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If there are no machines marked as inaccessible, or if all of them now +respond to the Cache Manager's probe, the output is: + +C + +Note that this message does not mean that all server machines in each +relevant cell are running. The output indicates the status of only +those machines that the Cache Manager probes. + +If a machine fails to respond to the probe within the timeout period, +the output begins with the string: + +C + +and lists the hostname of each machine on its own line. The Cache +Manager stores machine records by Internet address, so the format of +each hostname (uppercase or lowercase letters, or an Internet address +in dotted decimal format) depends on how the local cell's name service +translates it at the time the command is issued. If a server machine +is multihomed, the output lists only one of its interfaces (usually, +the currently most preferred one). + +If the B<-interval> argument is provided with a value between B<1> and B<600>, +there is no output. If the value is 0, the output reports the probe +interval as follows: + +C secs> + +=head1 EXAMPLES + +The following command displays the Cache Manager's current list of +unresponsive machines in the local cell, rather than probing them +again. The output indicates that if there were any machines marked +inaccessible, they all responded to the previous probe. + + fs checkservers -fast + All servers are running. + +The following example probes machines in the Cache Manager's memory +list that belong to the B cell: + + fs checkservers -cell stateu.edu + All servers are running. + +The following example probes all server machines in the Cache +Manager's memory list. It reports that two machines did not respond to +the probe. + + fs checkservers -all + These servers unavailable due to network or server problems: + fs1.abc.com SV3.STATE.EDU. + +=head1 PRIVILEGE REQUIRED + +To set the probe interval, the issuer must be logged in as the local +superuser B. Otherwise, no privilege is required. + +=head1 CAVEATS + +The command can take quite a while to complete, if a number of +machines do not respond to the Cache Manager's probe. The Cache +Manager probes machines sequentially and waits a standard timeout +period before marking the machine as unresponsive, to allow for slow +network communication. To make the command shell prompt return +quickly, put the command in the background. It is harmless to +interrupt the command by typing B or another interrupt signal. + +Note that the Cache Manager probes only server machines marked +inaccessible in its memory list. A server machine's absence from the +output does not necessarily mean that it is functioning, because it +possibly is not included in the memory list at all (if, for example, +the Cache Manager has not contacted it recently). For the same reason, +the output is likely to vary on different client machines. + +Unlike most C commands, the C command does not refer to +the AFSCELL environment variable. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_checkvolumes.pod b/doc/man-pages/pod/fs_checkvolumes.pod new file mode 100644 index 0000000000..b55c73ed91 --- /dev/null +++ b/doc/man-pages/pod/fs_checkvolumes.pod @@ -0,0 +1,54 @@ +=head1 NAME + +fs checkvolumes - Forces the Cache Manager to update volume-related information + +=head1 SYNOPSIS + +fs checkvolumes [B<-help>] + +fs checkv [B<-h>] + +=head1 DESCRIPTION + +The C command discards the table of mappings between +volume names and volume ID numbers that the Cache Manager stores in +memory and uses when fetching data from volumes. The next time an +application requests AFS data, the Cache Manager must contact the +Volume Location (VL) Server for volume location information, and then +an appropriate file server machine for the actual data. + +The Cache Manager updates the table of mappings periodically (by +default, hourly), but this command is useful if the issuer knows that +a volume's name has changed, or that new read-only replicas of a +volume have been released, because issuing it forces the Cache Manager +to reference the changed volume. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The following message confirms that the command ran successfully. + + All volumeID/name mappings checked. + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + diff --git a/doc/man-pages/pod/fs_cleanacl.pod b/doc/man-pages/pod/fs_cleanacl.pod new file mode 100644 index 0000000000..48ff64f5b2 --- /dev/null +++ b/doc/man-pages/pod/fs_cleanacl.pod @@ -0,0 +1,102 @@ +=head1 NAME + +fs cleanacl - Remove obsolete entries from an ACL + +=head1 SYNOPSIS + +fs cleanacl [B<-path> I [I ...]] [B<-help>] + +fs cl [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command removes from the access control list (ACL) of +each specified directory or file any entry that refers to a user or +group that no longer has a Protection Database entry. Such an entry +appears on the ACL as an AFS user ID number (UID) rather than a name, +because without a Protection Database entry, the File Server cannot +translate the UID into a name. + +Cleaning access control lists in this way not only keeps them from +becoming crowded with irrelevant information, but also prevents the +new possessor of a recycled AFS UID from obtaining access intended for +the former possessor of the AFS UID. (Note that recycling UIDs is not +recommended in any case.) + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each directory for which to clean the ACL (specifying a +filename cleans its directory's ACL). If this argument is +omitted, the current working directory's ACL is cleaned. + +Specify the read/write path to each directory, to avoid the +failure that results from attempting to change a read-only +volume. By convention, the read/write path is indicated by +placing a period before the cell name at the pathname's second +level (for example, B). For further discussion of +the concept of read/write and read-only paths through the +filespace, see the L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If there are no obsolete entries on the ACL, the following message +appears: + +Access list for I is fine. + +Otherwise, the output reports the resulting state of the ACL, +following the header + +Access list for I is now + +At the same time, the following error message appears for each file in +the cleaned directories: + +fs: 'I': Not a directory + +=head1 EXAMPLES + +The following example illustrates the cleaning of the ACLs on the +current working directory and two of its subdirectories. Only the +second subdirectory had obsolete entries on it. + + fs cleanacl -path . ./reports ./sources + Access list for . is fine. + Access list for ./reports is fine. + Access list for ./sources is now + Normal rights: + system:authuser rl + pat rlidwka + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on each directory's +ACL (or the ACL of each file's parent directory); the directory's +owner and the members of the B group have the +right implicitly, even if it does not appear on the ACL. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_copyacl.pod b/doc/man-pages/pod/fs_copyacl.pod new file mode 100644 index 0000000000..db77fe47df --- /dev/null +++ b/doc/man-pages/pod/fs_copyacl.pod @@ -0,0 +1,176 @@ +=head1 NAME + +fs copyacl - Copies an ACL from one directory to one or more other directories + +=head1 SYNOPSIS + +fs copyacl B<-fromdir> I +B<-todir> I [I ...] +[B<-clear>] [B<-id>] [B<-if>] [B<-help>] + +fs co B<-f> I +B<-t> I [I ...] +[B<-c>] [B<-id>] [B<-if>] [B<-h>] + +=head1 DESCRIPTION + +The C command copies the access control list (ACL) from a +source directory to each specified destination directory. The source +directory's ACL is unchanged, and changes to the destination +directory's ACL obey the following rules: + +=over + +=item * + +If an entry on the source ACL does not already exist on the +destination ACL, it is added. + +=item * + +If an entry exists on both the source and destination ACLs, the +permissions from the source ACL entry replace the current +permissions on the destination ACL entry. + +=item * + +If an entry on the destination ACL has no corresponding entry on +the source ACL, it is removed if the B<-clear> flag is included and +is unchanged otherwise. In other words, if the B<-clear> flag is +provided, the source ACL completely replaces the destination ACL. + +=back + +When using this command to copy ACLs between objects in DFS filespace +accessed via the AFS/DFS Migration Toolkit Protocol Translator, it is +possible to specify files, as well as directories, with the B<-fromdir> +and B<-todir> arguments. For more information on copying ACLs between DFS +directories and files, refer to the IBM AFS/DFS Migration Toolkit +Administration Guide and Reference. + +=head1 OPTIONS + +=over 4 + +=item B<-fromdir> I + +Specifies the source directory from which to copy the ACL. +(Specifying an AFS file copies its directory's ACL, but +specifying a DFS file copies its own ACL). A partial pathname +is interpreted relative to the current working directory. + +=item B<-todir> I [I ...] + +Specifies each directory for which to alter the ACL to match +the source ACL. (Specifying an AFS file halts the command with +an error, but specifying a DFS file alters the file's ACL). A +partial pathname is interpreted relative to the current working +directory. + +Specify the read/write path to each directory (or DFS file), to +avoid the failure that results from attempting to change a +read-only volume. By convention, the read/write path is +indicated by placing a period before the cell name at the +pathname's second level (for example, B). For +further discussion of the concept of read/write and read-only +paths through the filespace, see the L reference page. + +=item B<-clear> + +Replaces the ACL of each destination directory with the source +ACL. + +=item B<-id> + +Modifies the Initial Container ACL of each DFS directory named +by the B<-todir> argument, rather than the regular Object ACL. +This argument is supported only when both the source and each +destination directory reside in DFS and are accessed via the +AFS/DFS Migration Toolkit Protocol Translator. + +=item B<-if> + +Modifies the Initial Object ACL of each DFS directory named by +the B<-todir> argument, rather than the regular Object ACL. This +argument is supported only when both the source and each +destination directory reside in DFS and are accessed via the +AFS/DFS Migration Toolkit Protocol Translator. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example command copies the current working directory's +ACL to its subdirectory called B. Note that the source +directory's ACL is unaffected. Entries on the B directory's that +are not on the source ACL of the current directory remain unaffected +as well, because the -clear flag is not used. + + fs listacl . reports + Access list for . is + Normal rights: + pat rlidwka + smith rlidwk + Access list for reports is + Normal rights: + pat rl + pat:friends rl + Negative rights + jones rlidwka + + + fs copyacl -fromdir . -todir reports + + + fs listacl . reports + Access list for . is + Normal rights: + pat rlidwka + smith rlidwk + Access list for reports is + Normal rights: + pat rlidwka + pat:friends rl + smith rlidwk + Negative rights + jones rlidwka + +=head1 PRIVILEGE REQUIRED + +To copy an ACL between AFS objects, the issuer must have the B +(B) permission on the source directory's ACL and the B +(B) permission on each destination directory's ACL. If the +B<-fromdir> argument names a file rather than a directory, the issuer +must have both the B and B (B) permissions on the ACL of the file's +directory. + +To copy an ACL between DFS objects, the issuer must have the B +permission on the source directory or file's ACL and the B (B) +permission on each destination directory or file's ACL. + +=head1 CAVEATS + +Do not copy ACLs between AFS and DFS files or directories. The ACL +formats are incompatible. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +IBM AFS/DFS Migration Toolkit Administration Guide and Reference + +=cut diff --git a/doc/man-pages/pod/fs_diskfree.pod b/doc/man-pages/pod/fs_diskfree.pod new file mode 100644 index 0000000000..77876909b7 --- /dev/null +++ b/doc/man-pages/pod/fs_diskfree.pod @@ -0,0 +1,121 @@ +=head1 NAME + +fs diskfree - Displays information about the partition housing a directory or file + +=head1 SYNOPSIS + +fs diskfree [B<-path> I [I ...]] [B<-help>] + +fs df [B<-p> I [I ...]] [B<-h>] + +fs di [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command formats and displays information about the +partition that houses the volume containing the specified directory or +file, including its size and how much space is currently used. + +To display information about the volume itself, use the C +command. The C and C commands also display information +about a volume. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names a file or directory that resides on the partition about +which to produce output. Partial pathnames are interpreted +relative to the current working directory, which is also the +default value if this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output reports the following information about the volume and +partition that houses each file or directory: + +=over + +=item B + +The name of the volume + +=item B + +The partition's total size in kilobytes + +=item B + +The number of kilobytes used on the partition + +=item B + +The number of kilobytes available on the partition + +=item B<%used> + +The percentage of the partition's total space that is used (the +used statistic divided by the kbytes statistic, times 100) + +=back + +If the C<%used> statistic is greater than 90%, it is marked with the +string CEWARNING> at the right margin. + +If the volume is a read-only volume, the output includes information +about only one of the partitions that houses it, generally the one on +the file server machine with the lowest preference rank. To verify +which machine the output is referring to, use the C command +to list the volume's locations, and the C command to +display the size of each one. + +=head1 EXAMPLES + +The following example shows the output for the partitions housing the +volumes B and B: + + fs diskfree -path /afs/abc.com/usr/smith /afs/abc.com/sun4x_56/bin + Volume Name kbytes used avail %used + user.smith 4177920 3841258 336662 92% < (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 CAVEATS + +The partition-related statistics in this command's output do not +always agree with the corresponding values in the output of the +standard UNIX C command. The statistics reported by this command can +be up to five minutes old, because the Cache Manager polls the File +Server for partition information at that frequency. Also, on some +operating systems, the C command's report of partition size includes +reserved space not included in this command's calculation, and so is +likely to be about 10% larger. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_examine.pod b/doc/man-pages/pod/fs_examine.pod new file mode 100644 index 0000000000..b8ef607d1c --- /dev/null +++ b/doc/man-pages/pod/fs_examine.pod @@ -0,0 +1,126 @@ +=head1 NAME + +fs examine - Displays information about the volume containing a directory or file + +=head1 SYNOPSIS + +fs examine [B<-path> I [I ...]] [B<-help>] + +fs exa [B<-p> I [I ...]] [B<-h>] + +fs listvol [B<-p> I [I ...]] [B<-h>] + +fs listv [B<-p> I [I ...]] [B<-h>] + +fs lv [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays information about the volume +containing each specified directory or file, including its volume ID +number, quota and the percentage of its quota that is used. + +This command provides the most information about a volume, but the C command displays similar information in tabular format, and +the C command reports only the percentage of quota used. + +To set volume quota, use the C or C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names a file or directory that resides in the volume about +which to produce output. Partial pathnames are interpreted +relative to the current working directory, which is also the +default value if this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output displays information about the volume that houses each +specified directory or file, in the following format + + Volume status for vid = volume ID named volume name + Current offline message is message + Current disk quota is quota in kilobytes + Current blocks used are volume size in kilobytes + The partition has available partition blocks available out of + partition size + +where the first line specifies the volume's ID number and name. The +C line appears only if an administrator has +included the B<-offlinemsg> argument to the C command. The +remaining lines report, respectively, + +=over + +=item * + +the volume's quota in kilobytes, or the string C to +indicate an unlimited quota + +=item * + +the volume's current size in kilobytes + +=item * + +the number of blocks available and total size of the host +partition, both in kilobytes. + +=back + +=head1 EXAMPLES + +The following example shows the output for the volume B and +the partition housing it: + + fs examine -path /afs/abc.com/usr/smith + Volume status for vid = 50489902 named user.smith + Current maximum quota is 15000 + Current blocks used are 5073 + The partition has 336662 blocks available out of 4177920 + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 CAVEATS + +The partition-related statistics in this command's output do not +always agree with the corresponding values in the output of the +standard UNIX C command. The statistics reported by this command can +be up to five minutes old, because the Cache Manager polls the File +Server for partition information at that frequency. Also, on some +operating systems, the C command's report of partition size includes +reserved space not included in this command's calculation, and so is +likely to be about 10% larger. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_exportafs.pod b/doc/man-pages/pod/fs_exportafs.pod new file mode 100644 index 0000000000..671bf3f290 --- /dev/null +++ b/doc/man-pages/pod/fs_exportafs.pod @@ -0,0 +1,215 @@ +=head1 NAME + +fs exportafs - Reports or sets whether the machine can export AFS to clients of other +file systems + +=head1 SYNOPSIS + +fs exportafs B<-type> I +[B<-start> I] +[B<-convert> I] +[B<-uidcheck> I] +[B<-submounts> I] +[B<-help>] + +fs exp B<-t> I +[B<-st> I] +[B<-c> I] +[B<-u> I] +[B<-su> I] +[B<-help>] + +=head1 DESCRIPTION + +The C command sets (if the B<-start> argument is provided) or +reports (if it is omitted) whether the machine can reexport the AFS +filespace to clients of a non-AFS file system. To control certain +features of the translation protocol, use the following arguments: + +=over + +=item * + +To control whether the UNIX B and B mode bits on an AFS +file or directory are set to match the B mode bits when it is +exported to the non-AFS file system, use the B<-convert> argument. + +=item * + +To control whether tokens can be placed in a credential structure +identified by a UID that differs from the local UID of the entity +that is placing the tokens in the structure, use the B<-uidcheck> +argument. The most common use is to control whether issuers of the +C command can specify a value for its B<-id> argument that does +not match their local UID on the NFS/AFS translator machine. + +=item * + +To control whether users can create mounts in the non-AFS +filespace to an AFS directory other than B, use the B<-submounts> +argument. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-type> I + +Names the alternate file system to which to reexport the AFS +filespace. The only acceptable value is B, in lowercase +letters only. + +=item B<-start> I + +Enables the local machine to reexport the AFS filespace if the +value is B, or disables it if the value is B. Omit this +argument to report the current setting for all of the +configurable parameters. + +=item B<-convert> I + +Controls the setting of the UNIX B and B mode bits on +AFS files and directories exported to the non-AFS file system. +If the value is B, they are set to match the owner mode bits. +If the value is B, the bits are not changed. If this argument +is omitted, the default value is B. + +=item B<-uidcheck> I + +Controls whether tokens can be placed in a credential structure +identified by a UID that differs from the local UID of the +entity that is placing the tokens in the structure. + +=over + +=item * + +If the value is B, the UID that identifies the credential +structure must match the local UID. + +With respect to the C command, this value means that the +value of B<-id> argument must match the issuer's local UID on +the translator machine. In practice, this setting makes it +pointless to include the B<-id> argument to the C command, +because the only acceptable value (the issuer's local UID) is +already used when the B<-id> argument is omitted. + +Enabling UID checking also makes it impossible to issue the +C and C commands on a client machine of the non-AFS +file system even though it is a system type supported by AFS. +For an explanation, see the reference page for the C +command. + +=item * + +If the value is B (the default), tokens can be assigned to +a local UID in the non-AFS file system that does not match +the local UID of the entity assigning the tokens. + +With respect to the C command, it means that the issuer +can use the B<-id> argument to assign tokens to a local UID on +the NFS client machine that does not match his or her local +UID on the translator machine. (An example is assigning +tokens to the MFS client machine's local superuser B.) +This setting allows more than one issuer of the C command +to make tokens available to the same user on the NFS client +machine. Each time a different user issues the C command +with the same value for the B<-id> argument, that user's tokens +overwrite the existing ones. This can result in unpredictable +access for the user on the NFS client machine. + +=back + +=item B<-submounts> I + +Controls whether a user of the non-AFS filesystem can mount any +directory in the AFS filespace other than the top-level B +directory. If the value is B, such submounts are allowed. If +the value is off, only mounts of the B directory are +allowed. If this argument is omitted, the default value is B. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the machine is not even configured as a server of the non-AFS file +system, the following message appears: + +Sorry, the I-exporter type is currently not supported on this AFS client + +If the machine is configured as a server of the non-AFS file system +but is not currently enabled to reexport AFS to it (because the B<-start> +argument to this command is not set to on), the message is as follows: + +'I' translator is disabled + +If the machine is enabled to reexport AFS, the following message +precedes messages that report the settings of the other parameters. + +'I' translator is enabled with the following options: + +The following messages indicate that the B<-convert> argument is set to +B or B respectively: + + Running in convert owner mode bits to world/other mode + Running in strict unix mode + +The following messages indicate that the B<-uidcheck> argument is set to +B or B respectively: + + Running in strict 'passwd sync' mode + Running in no 'passwd sync' mode + +The following messages indicate that the B<-submounts> argument is set to +B or B respectively: + + Allow mounts of /afs/.. subdirs + Only mounts to /afs allowed + +=head1 EXAMPLES + +The following example shows that the local machine can export AFS to +NFS client machines. + + fs exportafs nfs + 'nfs' translator is enabled with the following options: + Running in convert owner mode bits to world/other mode + Running in no 'passwd sync' mode + Only mounts to /afs allowed + +The following example enables the machine as an NFS server and +converts the UNIX B and B mode bits on exported AFS +directories and files to match the UNIX B mode bits. + + fs exportafs -type nfs -start on -convert on + +The following example disables the machine from reexporting AFS to NFS +client machines: + + fs exportafs -type nfs -start off + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_flush.pod b/doc/man-pages/pod/fs_flush.pod new file mode 100644 index 0000000000..107a3d2bef --- /dev/null +++ b/doc/man-pages/pod/fs_flush.pod @@ -0,0 +1,85 @@ +=head1 NAME + +fs flush - Forces the Cache Manager to discard a cached file or directory + +=head1 SYNOPSIS + +fs flush [B<-path> I [I ...]] [B<-help>] + +fs flush [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command removes from the cache all data and status +information associated with each specified file or directory. The next +time an application requests data from the flushed directory or file, +the Cache Manager fetches the most current version from a File Server, +along with a new callback (if necessary) and associated status +information. This command has no effect on two types of data: + +=over + +=item 1. + +Data in application program buffers + +=item 2. + +Data that has been changed locally and written to the cache but +not yet written to the copy on the file server machine + +=back + +To flush all data in the cache that was fetched from the same volume +as a specified file or directory, use the C command. To +flush a corrupted mount point, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each file or directory to flush from the cache. If it is +a directory, only the directory element itself is flushed, not +data cached from files or subdirectories that reside in it. +Partial pathnames are interpreted relative to the current +working directory, which is also the default value if this +argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command flushes from the cache the file B in +the current working directory and all data from the subdirectory +B: + + fs flush -path projectnotes ./plans/* + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_flushmount.pod b/doc/man-pages/pod/fs_flushmount.pod new file mode 100644 index 0000000000..ba8615c493 --- /dev/null +++ b/doc/man-pages/pod/fs_flushmount.pod @@ -0,0 +1,76 @@ +=head1 NAME + +fs flushmount - Forces the Cache Manager to discard a mount point + +=head1 SYNOPSIS + +fs flushmount [B<-path> I [I ...]] [B<-help>] + +fs flushm [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command removes from the cache all information +associated with each mount point named by the B<-path> argument. The next +time an application accesses the mount point, the Cache Manager +fetches the most current version of it from the File Server. Data +cached from the associated volume is not affected. + +The command's intended use is to discard information about mount +points that has become corrupted in the cache. (The Cache Manager +periodically refreshes cached mount points, but the only other way to +discard them immediately is to reinitialize the Cache Manager by +rebooting the machine.) Symptoms of a corrupted mount point included +garbled output from the C command, and failed attempts to +change directory to or list the contents of a mount point. + +To flush cached data rather than a mount point, use the C or C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each mount point to flush from the cache. Partial +pathnames are interpreted relative to the current working +directory, which is also the default value if this argument is +omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command flushes from the cache the mount point for user +B's home directory: + + fs flushm /afs/abc.com/usr/pat + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_flushvolume.pod b/doc/man-pages/pod/fs_flushvolume.pod new file mode 100644 index 0000000000..6b63d16ea0 --- /dev/null +++ b/doc/man-pages/pod/fs_flushvolume.pod @@ -0,0 +1,84 @@ +=head1 NAME + +fs flushvolume - Forces the Cache Manager to discard all cached data from the volume +containing a file or directory + +=head1 SYNOPSIS + +fs flushvolume [B<-path> I [I ...]] [B<-help>] + +fs flushv [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command removes from the cache all data that was +fetched from the same volume as each specified directory or file. It +does not discard cached status information. The next time an +application requests data from a flushed directory or file, the Cache +Manager fetches the most current version from a File Server, along +with a new callback (if necessary) and associated status information. +This command has no effect on two types of data: + +=over + +=item 1. + +Data in application program buffers + +=item 2. + +Data that has been changed locally and written to the cache but +not yet written to the copy on the file server machine + +=back + +To discard the data and status information associated with individual +files and directories, use the C command. To flush a corrupted +mount point, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names a file or directory from each volume for which to discard +all cached data. Partial pathnames are interpreted relative to +the current working directory, which is also the default value +if this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command flushes from the cache all data fetched from the +volume that contains the current working directory: + + fs flushvolume + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_getcacheparms.pod b/doc/man-pages/pod/fs_getcacheparms.pod new file mode 100644 index 0000000000..9813e7abec --- /dev/null +++ b/doc/man-pages/pod/fs_getcacheparms.pod @@ -0,0 +1,66 @@ +=head1 NAME + +fs getcacheparms - Displays the current size of the cache and the amount being used + +=head1 SYNOPSIS + +fs getcacheparms [B<-help>] + +fs getca [B<-h>] + +=head1 DESCRIPTION + +The C command displays the current size of the cache +(which can be in memory or on disk), and the amount currently in use. + +The reported statistics are from kernel memory, so the reported size +can differ from the setting specified in the B +file on a machine using a disk cache, if the C command +has been used to alter cache size. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output reports + +AFS using I of the cache's available I 1K byte blocks. + +where I is the number of kilobyte blocks currently used to +cache data and status information, and I is the total current cache +size. + +=head1 EXAMPLES + +The following example shows the output on a machine with a 25000 +kilobyte cache. + + fs getcacheparms + AFS using 22876 of the cache's available 25000 1K byte blocks. + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_getcellstatus.pod b/doc/man-pages/pod/fs_getcellstatus.pod new file mode 100644 index 0000000000..a935f6af7c --- /dev/null +++ b/doc/man-pages/pod/fs_getcellstatus.pod @@ -0,0 +1,70 @@ +=head1 NAME + +fs getcellstatus - Reports whether the machine can run setuid programs from a specified +cell + +=head1 SYNOPSIS + +fs getcellstatus B<-cell> I [I ...] [B<-help>] + +fs getce B<-c> I [I ...] [B<-h>] + +=head1 DESCRIPTION + +The C command reports whether the Cache Manager allows +programs fetched from each specified cell to run with setuid +permission. To set a cell's setuid status, use the C command; +its reference page fully describes how AFS treats setuid programs. + +=head1 OPTIONS + +=over 4 + +=item B<-cell> I [I ...] + +Names each cell for which to report setuid status. Provide the +fully qualified domain name, or a shortened form that +disambiguates it from the other cells listed in the local +B file. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output reports one of the following two values as appropriate: + +Cell I status: setuid allowed + +Cell I status: no setuid allowed + +=head1 EXAMPLES + +The following example indicates that programs from the cell B +are not allowed to run with setuid permission. + + fs getcellstatus abc.com + Cell abc.com status: no setuid allowed + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_getclientaddrs.pod b/doc/man-pages/pod/fs_getclientaddrs.pod new file mode 100644 index 0000000000..f7cdb94a1b --- /dev/null +++ b/doc/man-pages/pod/fs_getclientaddrs.pod @@ -0,0 +1,109 @@ +=head1 NAME + +fs getclientaddrs - Displays the client interfaces to register with the File Server + +=head1 SYNOPSIS + +fs getclientaddrs [B<-help>] + +fs gc [B<-h>] + +fs getcl [B<-h>] + +=head1 DESCRIPTION + +The C command displays the IP addresses of the +interfaces that the local Cache Manager registers with a File Server +when first establishing a connection to it. + +The File Server uses the addresses when it initiates a remote +procedure call (RPC) to the Cache Manager (as opposed to responding to +an RPC sent by the Cache Manager). There are two common circumstances +in which the File Server initiates RPCs: when it breaks callbacks and +when it pings the client machine to verify that the Cache Manager is +still accessible. + +If an RPC to that interface fails, the File Server simultaneously +sends RPCs to all of the other interfaces in the list, to learn which +of them are still available. Whichever interface replies first is the +one to which the File Server then sends pings and RPCs to break +callbacks. + +The L reference page explains how the Cache Manager +constructs the list automatically in kernel memory as it initializes, +and how to use that command to alter the kernel list after +initialization. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output displays the IP address of each interface that the Cache +Manager is currently registering with File Server processes that it +contacts, with one address per line. The File Server initially uses +the first address for breaking callbacks and pinging the Cache +Manager, but the ordering of the other interfaces is not meaningful. + +=head1 EXAMPLES + +The following example displays the two interfaces that the Cache +Manager is registering with File Servers. + + fs getclientaddrs + 192.12.105.68 + 192.12.108.84 + +=head1 PRIVILEGE REQUIRED + +None + +=head1 CAVEATS + +The File Server uses the list of interfaces displayed by this command +only when selecting an alternative interface after a failed attempt to +break a callback or ping the Cache Manager. When responding to the +Cache Manager's request for file system data, the File Server replies +to the interface which the Cache Manager used when sending the +request. If the File Server's reply to a data request fails, the file +server machine's network routing configuration determines which +alternate network routes to the client machine are available for +resending the reply. + +The displayed list applies to all File Servers to which the Cache +Manager connects in the future. It is not practical to register +different sets of addresses with different File Servers, because it +requires using the C command to change the list and +then rebooting each relevant File Server immediately. + +The displayed list is not necessarily governing the behavior of a +given File Server, if an administrator has issued the C command since the Cache Manager first contacted that +File Server. It determines only which addresses the Cache Manager +registers when connecting to File Servers in the future. + +The list of interfaces does not influence the Cache Manager's choice +of interface when establishing a connection to a File Server. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_getserverprefs.pod b/doc/man-pages/pod/fs_getserverprefs.pod new file mode 100644 index 0000000000..1822a3a600 --- /dev/null +++ b/doc/man-pages/pod/fs_getserverprefs.pod @@ -0,0 +1,174 @@ +=head1 NAME + +fs getserverprefs - Displays the Cache Manager's preference ranks for file server or VL +Server machines + +=head1 SYNOPSIS + +fs getserverprefs [B<-file> I] +[B<-numeric>] [B<-vlservers>] [B<-help>] + +fs gets [B<-f> I] [B<-n>] [B<-v>] [B<-h>] + +fs gp [B<-f> I] [B<-n>] [B<-v>] [B<-h>] + +=head1 DESCRIPTION + +The C command displays preference ranks for file +server machine interfaces (file server machines run the B process) +or, if the B<-vlserver> flag is provided, for Volume Location (VL) Server +machines (which run the B process). For file server machines, +the Cache Manager tracks up to 15 interfaces per machine and assigns a +separate rank to each interface. The ranks indicate the order in which +the local Cache Manager attempts to contact the interfaces of machines +that are housing a volume when it needs to fetch data from the volume. +For VL Server machines, the ranks indicate the order in which the +Cache Manager attempts to contact a cell's VL Servers when requesting +VLDB information. For both types of rank, lower integer values are +more preferred. + +The Cache Manager stores ranks in kernel memory. Once set, a rank +persists until the machine reboots, or until the C +command is used to change it. The reference page for the C command explains how the Cache Manager sets default +ranks, and how to use that command to change the default values. + +Default VL Server ranks range from 10,000 to 10,126, and the Cache +Manager assigns them to every machine listed in its copy of the +B file. When the Cache Manager needs to fetch +VLDB information from a cell, it compares the ranks for the VL Server +machines belonging to that cell, and attempts to contact the VL Server +with the lowest integer rank. If the Cache Manager cannot reach the VL +Server (because of server process, machine or network outage), it +tries to contact the VL Server with the next lowest integer rank, and +so on. If all of a cell's VL Server machines are unavailable, the +Cache Manager cannot fetch data from the cell. + +Default file server ranks range from 5,000 to 40,000, excluding the +range used for VL Servers (10,000 to 10,126); the maximum possible +rank is 65,534. When the Cache Manager needs to fetch data from a +volume, it compares the ranks for the interfaces of machines that +house the volume, and attempts to contact the interface that has the +lowest integer rank. If it cannot reach the B process via +that interface (because of server process, machine or network outage), +it tries to contact the interface with the next lowest integer rank, +and so on. If it cannot reach any of the interfaces for machines that +house the volume, it cannot fetch data from the volume. + +For both file server machines and VL Server machines, it is possible +for a machine or interface in a foreign cell to have the same rank as +a machine or interface in the local cell. This does not present a +problem, because the Cache Manager only ever compares ranks for +machines belonging to one cell at a time. + +=head1 OPTIONS + +=over 4 + +=item B<-file> I + +Specifies the full pathname of a file to which to write the +preference ranks. If the specified file already exists, the +command overwrites its contents. If the pathname is invalid, +the command fails. If this argument is not provided, the +preference ranks appear on the standard output stream. + +=item B<-numeric> + +Displays the IP addresses of file server machine interfaces or +VL Server machines, rather than their hostnames. If this +argument is not provided, the C command interpreter has the IP +addresses translated to hostnames such as B. + +=item B<-vlservers> + +Displays preference ranks for VL Server machines rather than +file server machine interfaces. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output consists of a separate line for each file server machine +interface or VL Server machine, pairing the machine's hostname or IP +address with its rank. The Cache Manager stores IP addresses in its +kernel list of ranks, but the command by default identifies interfaces +by hostname, by calling a translation routine that refers to either +the cell's name service (such as the Domain Name Server) or the local +host table. If an IP address appears in the output, it is because the +translation attempt failed. To bypass the translation step and display +IP addresses rather than hostnames, include the B<-numeric> flag. This +can significantly speed the production of output. + +By default, the command writes to the standard output stream. Use the +B<-file> argument to write the output to a file instead. + +=head1 EXAMPLES + +The following example displays the local Cache Manager's preference +ranks for file server machines. The local machine belongs to the AFS +cell named B, and in this example the ranks of file server +machines in its local cell are lower than the ranks of file server +machines from the foreign cell, B. It is not possible to +translate the IP addresses of two machines on the 138.255 network. + + fs getserverprefs + fs2.abc.com 20007 + fs3.abc.com 30002 + fs1.abc.com 20011 + fs4.abc.com 30010 + server1.def.com 40002 + 138.255.33.34 40000 + server6.def.com 40012 + 138.255.33.37 40005 + +The following example shows hows the output displays IP addresses when +the B<-numeric> flag is included, and illustrates how network proximity +determines default ranks (as described on the L +reference page). The local machine has IP address 192.12.107.210, and +the two file server machines on its subnetwork have ranks of 20,007 +and 20,011. The two file server machines on a different subnetwork of +the local machine's network have higher ranks, 30,002 and 30,010, +whereas the ranks of the remaining machines range from 40,000 to +40,012 because they are in a completely different network. + + fs getserverprefs -numeric + 192.12.107.214 20007 + 192.12.105.99 30002 + 192.12.107.212 20011 + 192.12.105.100 30010 + 138.255.33.41 40002 + 138.255.33.34 40000 + 138.255.33.36 40012 + 138.255.33.37 40005 + +The example shows how the B<-vlservers> flag displays preference ranks +for VL Server machines: + + fs getserverprefs -vlservers + fs2.abc.com 10052 + fs3.abc.com 10113 + fs1.abc.com 10005 + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_help.pod b/doc/man-pages/pod/fs_help.pod new file mode 100644 index 0000000000..21a55484a1 --- /dev/null +++ b/doc/man-pages/pod/fs_help.pod @@ -0,0 +1,95 @@ +=head1 NAME + +fs help - Displays the syntax of specified C commands or lists functional +descriptions of all C commands + +=head1 SYNOPSIS + +fs help [B<-topic> I [I ...]] [B<-help>] + +fs h [B<-t> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the complete online help entry (short +description and syntax statement) for each command operation code +specified by the B<-topic> argument. If the B<-topic> argument is omitted, +the output includes the first line (name and short description) of the +online help entry for every C command. + +To display every C command whose name or short description includes a +specified keyword, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I [I ...] + +Indicates each command for which to display the complete online +help entry. Omit the C part of the command name, providing +only the operation code (for example, specify C, not C). If this argument is omitted, the output briefly +describes every C command. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The online help entry for each C command consists of the following +two or three lines: + +=over + +=item * + +The first line names the command and briefly describes its +function. + +=item * + +The second line lists aliases for the command, if any. + +=item * + +The final line, which begins with the string Usage, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in +this document. + +=back + +=head1 EXAMPLES + +The following command displays the online help entry for the C +command: + + fs help setacl + fs setacl: set access control list + aliases: sa + Usage: fs setacl -dir + -acl + + [-clear] [-negative] [-help] + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_listacl.pod b/doc/man-pages/pod/fs_listacl.pod new file mode 100644 index 0000000000..147bc7c469 --- /dev/null +++ b/doc/man-pages/pod/fs_listacl.pod @@ -0,0 +1,196 @@ +=head1 NAME + +fs listacl - Displays ACLs + +=head1 SYNOPSIS + +fs listacl [B<-path> I [I ...]] [B<-id>] [B<-if>] [B<-help>] + +fs la [B<-p> I [I ...]] [B<-id>] [B<-if>] [B<-h>] + +fs lista [B<-p> I [I ...]] [B<-id>] [B<-if>] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the access control list (ACL) +associated with each specified file, directory, or symbolic link. The +specified element can reside in the DFS filespace if the issuer is +using the AFS/DFS Migration Toolkit Protocol Translator to access DFS +data (and DFS does implement per-file ACLs). To display the ACL of the +current working directory, omit the B<-path> argument. + +To alter an ACL, use the C command. To copy an ACL from one +directory to another, use the C command. To remove obsolete +entries from an ACL, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each directory or file for which to display the ACL. For +AFS files, the output displays the ACL from the file's parent +directory; DFS files do have their own ACL. Incomplete +pathnames are interpreted relative to the current working +directory, which is also the default value if this argument is +omitted. + +=item B<-id> + +Displays the Initial Container ACL of each DFS directory. This +argument is supported only on DFS directories accessed via the +AFS/DFS Migration Toolkit Protocol Translator. + +=item B<-if> + +Displays the Initial Object ACL of each DFS directory. This +argument is supported only on DFS directories accessed via the +AFS/DFS Migration Toolkit Protocol Translator. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of the output for each file, directory, or symbolic +link reads as follows: + +Access list for I is + +If the issuer used shorthand notation in the pathname, such as the +period (.) to represent the current current directory, that notation +sometimes appears instead of the full pathname of the directory. + +Next, the C header precedes a list of users and groups who +are granted the indicated permissions, with one pairing of user or +group and permissions on each line. If negative permissions have been +assigned to any user or group, those entries follow a C +header. The format of negative entries is the same as those on the +C section of the ACL, but the user or group is denied +rather than granted the indicated permissions. + +AFS does not implement per-file ACLs, so for a file the command +displays the ACL on its directory. The output for a symbolic link +displays the ACL that applies to its target file or directory, rather +than the ACL on the directory that houses the symbolic link. + +The permissions for AFS enable the possessor to perform the indicated +action: + +=over + +=item B + +(B): change the entries on the ACL + +=item B + +(B): remove files and subdirectories from the directory or +move them to other directories + +=item B + +(B): add files or subdirectories to the directory by +copying, moving or creating + +=item B + +(B): set read locks or write locks on the files in the +directory + +=item B + +(B): list the files and subdirectories in the directory, +stat the directory itself, and issue the C command to +examine the directory's ACL + +=item B + +(B): read the contents of files in the directory; issue the +C command to stat the elements in the directory + +=item B + +(B): modify the contents of files in the directory, and +issue the UNIX C command to change their mode bits + +=item B + +Have no default meaning to the AFS server processes, but are +made available for applications to use in controlling access to +the directory's contents in additional ways. The letters must +be uppercase. + +=back + +For DFS files and directories, the permissions are similar, except +that the DFS B (B) permission replaces the AFS B (B) +permission, DFS B (B) replaces AFS B (B), and there is +no DFS equivalent to the AFS B (B) permission. The meanings of the +various permissions also differ slightly, and DFS does not implement +negative permissions. For a complete description of DFS permissions, +see the DFS documentation and the IBM AFS/DFS Migration Toolkit +Administration Guide and Reference. + +=head1 EXAMPLES + +The following command displays the ACL on the home directory of the +user B (the current working directory), and on its B +subdirectory. + + fs listacl -path . private + Access list for . is + Normal rights: + system:authuser rl + pat rlidwka + pat:friends rlid + Negative rights: + smith rlidwka + Access list for private is + Normal rights: + pat rlidwka + +=head1 PRIVILEGE REQUIRED + +If the B<-path> argument names an AFS directory, the issuer must have the +B (B) permission on its ACL and the ACL for every directory that +precedes it in the pathname. + +If the B<-path> argument names an AFS file, the issuer must have the B +(B) and B (B) permissions on the ACL of the file's directory, +and the l permission on the ACL of each directory that precedes it in +the pathname. + +If the B<-path> argument names a DFS directory or file, the issuer must +have the B (B) permission on its ACL and on the ACL of each +directory that precedes it in the pathname. + +=head1 CAVEATS + +Placing a user or group on the C section of the ACL does +not guarantee denial of permissions, if the C section +grants the permissions to members of the B group. In that +case, the user needs only to issue the C command to obtain the +permissions granted to the B group. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +IBM AFS/DFS Migration Toolkit Administration Guide and Reference + +=cut diff --git a/doc/man-pages/pod/fs_listcells.pod b/doc/man-pages/pod/fs_listcells.pod new file mode 100644 index 0000000000..9577f861b5 --- /dev/null +++ b/doc/man-pages/pod/fs_listcells.pod @@ -0,0 +1,83 @@ +=head1 NAME + +fs listcells - Displays the database server machines in each cell known to the Cache +Manager + +=head1 SYNOPSIS + +fs listcells [B<-numeric>] [B<-help>] + +fs listc [B<-n>] [B<-h>] + +=head1 DESCRIPTION + +The C command formats and displays the list of the database +server machines that the Cache Manager stores in kernel memory for its +home cell and foreign cells. + +At each reboot of the client machine, the Cache Manager copies the +contents of B into kernel memory. To modify the +list between reboots, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-numeric> + +Displays each database server machine's IP address rather than +hostname. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output includes a line for each cell included in the Cache +Manager's kernel memory list, in the following format: + +Cell I on hosts I + +The Cache Manager stores IP addresses, but by default has them +translated to hostnames before reporting them, by passing them to the +cell's name service (such as the Domain Name Service or a local host +table). The name service sometimes returns hostnames in uppercase +letters, or an IP address if it cannot resolve a name. + +Using the B<-numeric> flag bypasses the translation to hostnames, which +can result in significantly faster production of output. The output +includes IP addresses only. + +=head1 EXAMPLES + +The following example shows output for several cells as illustrations +of the different formats for machine names: + + fs listcells + Cell abc.com on hosts fs1.abc.com fs2.abc.com fs3.abc.com + Cell stateu.edu on hosts DB1.FS.STATEU.EDU + DB2.FS.STATEU.EDU DB3.FS.STATEU.EDU + Cell def.gov on hosts 138.255.0.2 sv3.def.gov + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_listquota.pod b/doc/man-pages/pod/fs_listquota.pod new file mode 100644 index 0000000000..02c75b5ef7 --- /dev/null +++ b/doc/man-pages/pod/fs_listquota.pod @@ -0,0 +1,111 @@ +=head1 NAME + +fs listquota - Displays quota information for the volume containing a file or +directory. + +=head1 SYNOPSIS + +fs listquota [B<-path> I [I ...]] [B<-help>] + +fs listq [B<-p> I [I ...]] [B<-h>] + +fs lq [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays information about the volume +containing each specified directory or file (its name, quota, and +amount of disk space used), along with an indicator of the percentage +of space used on the host partition. + +To display more information about the host partition, use the C command. + +To set volume quota, use the fs setquota or C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names a file or directory that resides in the volume about +which to produce output. Partial pathnames are interpreted +relative to the current working directory, which is also the +default value if this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output displays information about the volume that houses each +specified directory or file, in a tabular format that uses the +following headers: + +=over + +=item B + +The name of the volume. + +=item B + +The volume's quota in kilobytes, or the string no limit to +indicate an unlimited quota. + +=item B + +The number of kilobytes of quota used. + +=item B<% Used> + +The percentage of the volume's quota that is used (the Used +statistic divided by the Quota statistic, times 100). + +=item B + +The percentage of space used on the partition that houses the +volume. Although not directly related to how much of the user's +quota is used, it is reported because a full partition can +cause writing of data back to the volume to fail even when the +volume has not reached its quota. + +=back + +=head1 EXAMPLES + +The following example shows the output for the volume B: + + fs listquota -path /afs/abc.com/usr/smith + Volume Name Quota Used % Used Partition + user.smith 15000 5071 34% 86% + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_lsmount.pod b/doc/man-pages/pod/fs_lsmount.pod new file mode 100644 index 0000000000..eba6111446 --- /dev/null +++ b/doc/man-pages/pod/fs_lsmount.pod @@ -0,0 +1,130 @@ +=head1 NAME + +fs lsmount - Reports the volume for which a directory is the mount point. + +=head1 SYNOPSIS + +fs lsmount B<-dir> I [I ...] [B<-help>] + +fs ls B<-d> I [I ...] [B<-h>] + +=head1 DESCRIPTION + +The C command reports the volume for which each specified +directory is a mount point, or indicates with an error message that a +directory is not a mount point or is not in AFS. + +To create a mount point, use the C command. To remove one, +use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-dir> I [I ...] + +Names the directory that serves as a mount point for a volume. +The last element in the pathname provided must be an actual +name, not a shorthand notation such as one or two periods (. or +..). + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If the specified directory is a mount point, the output is of the +following form: + +'I' is a mount point for volume 'I' + +where + +=over + +=item * + +A number sign (#) precedes the I string for a regular +mount point. + +=item * + +A percent sign (%) precedes the I string for a +read/write mount point. + +=item * + +A cell name and colon (:) follow the number or percent sign and +precede the I string for a cellular mount point. + +=back + +The L reference page explains how the Cache Manager +interprets each of the three types of mount points. + +If the directory is a symbolic link to a mount point, the output is of +the form: + +'I' is a symbolic link, leading to a mount point for volume 'I' + +If the directory is not a mount point or is not in AFS, the output +reads: + +'I' is not a mount point. + +If the output is garbled, it is possible that the mount point has +become corrupted in the local AFS client cache. Use the C +command to discard it, which forces the Cache Manager to refetch the +mount point. + +=head1 EXAMPLES + +The following example shows the mount point for the home directory of +user B: + + fs lsmount /afs/abc.com/usr/smith + '/afs/abc.com/usr/smith' is a mount point for volume '#user.smith' + +The following example shows both the regular and read/write mount +points for the ABC Corporation cell's C volume. + + fs lsmount /afs/abc.com + '/afs/abc.com' is a mount point for volume '#root.cell' + + fs lsmount /afs/.abc.com + '/afs/.abc.com' is a mount point for volume '%root.cell' + +The following example shows a cellular mount point: the State +University cell's C volume as mounted in the ABC Corporation +cell's tree. + + fs lsmount /afs/stateu.edu + '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell' + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-dir> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_messages.pod b/doc/man-pages/pod/fs_messages.pod new file mode 100644 index 0000000000..f69f653e8b --- /dev/null +++ b/doc/man-pages/pod/fs_messages.pod @@ -0,0 +1,98 @@ +=head1 NAME + +fs messages - Sets whether the Cache Manager writes log messages + +=head1 SYNOPSIS + +fs messages [B<-show> I<[user|console|all|none]>] [B<-help>] + +fs me [B<-s> I<[user|console|all|none]>] [B<-h>] + +=head1 DESCRIPTION + +The C command controls whether the Cache Manager displays +status and warning messages on user screens, the client machine +console, on both, or on neither. + +There are two types of Cache Manager messages: + +=over + +=item * + +User messages provide user-level status and warning information, +and the Cache Manager directs them to user screens. + +=item * + +Console messages provide system-level status and warning +information, and the Cache Manager directs them to the client +machine's designated console. + +=back + +Disabling messaging completely is not recommended, because the +messages provide useful status and warning information. + +=head1 OPTIONS + +=over 4 + +=item B<-show> I<[user|console|all|none]> + +Specifies the types of messages to display. Choose one of the +following values: + +=over + +=item B + +Send user messages to user screens + +=item B + +Send console messages to the console + +=item B + +Send user messages to user screens and console messages +to the console (the default if the B<-show> argument is +omitted) + +=item B + +Do not send any messages to user screens or the console + +=back + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command instructs the Cache Manager to display both +types of messages: + + fs messages -show all + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_mkmount.pod b/doc/man-pages/pod/fs_mkmount.pod new file mode 100644 index 0000000000..7b1c1625ca --- /dev/null +++ b/doc/man-pages/pod/fs_mkmount.pod @@ -0,0 +1,274 @@ +=head1 NAME + +fs mkmount - Creates a mount point for a volume + +=head1 SYNOPSIS + +fs mkmount B<-dir> I B<-vol> I [B<-cell> I] +[B<-rw>] [B<-fast>] [B<-help>] + +fs mk B<-d> I B<-v> I [B<-c> I] [B<-r>] [B<-f>] [B<-h>] + +=head1 DESCRIPTION + +The C command creates a mount point for the volume named by +the B<-vol> argument at the location in the AFS file space specified by +the B<-dir> argument. The mount point looks like a standard directory +element, and serves as the volume's root directory, but is actually a +special file system object that refers to an AFS volume. When the +Cache Manager first encounters a given mount point during pathname +traversal, it contacts the VL Server to learn which file server +machines house the indicated volume, then fetches a copy of the +volume's root directory from the appropriate file server machine. + +It is possible, although not recommended, to create more than one +mount point to a volume. The Cache Manager can become confused if a +volume is mounted in two places along the same path through the +filespace. + +The Cache Manager observes three basic rules as it traverses the AFS +filespace and encounters mount points: + +=over + +=item * + +B: Access Backup and Read-only Volumes When Specified + +When the Cache Manager encounters a mount point that specifies a +volume with either a B<.readonly> or a B<.backup> extension, it accesses +that type of volume only. If a mount point does not have either a +B<.backup> or B<.readonly> extension, the Cache Manager uses Rules 2 and +3. + +For example, the Cache Manager never accesses the read/write +version of a volume if the mount point names the backup version. +If the specified version is inaccessible, the Cache Manager +reports an error. + +=item * + +B: Follow the Read-only Path When Possible + +If a mount point resides in a read-only volume and the volume that +it references is replicated, the Cache Manager attempts to access +a read-only copy of the volume; if the referenced volume is not +replicated, the Cache Manager accesses the read/write copy. The +Cache Manager is thus said to prefer a I path through the +filespace, accessing read-only volumes when they are available. + +The Cache Manager starts on the read-only path in the first place +because it always accesses a read-only copy of the B volume +if it exists; the volume is mounted at the root of a cell's AFS +filespace (named B by convention). That is, if the B +volume is replicated, the Cache Manager attempts to access a +read-only copy of it rather than the read/write copy. This rule +then keeps the Cache Manager on a read-only path as long as each +successive volume is replicated. The implication is that both the +B and B volumes must be replicated for the Cache +Manager to access replicated volumes mounted below them in the AFS +filespace. The volumes are conventionally mounted at the B and +BI directories, respectively. + +=item * + +B: Once on a Read/write Path, Stay There + +If a mount point resides in a read/write volume and the volume +name does not have a B<.readonly> or a B<.backup> extension, the Cache +Manager attempts to access only the a read/write version of the +volume. The access attempt fails with an error if the read/write +version is inaccessible, even if a read-only version is +accessible. In this situation the Cache Manager is said to be on a +I and cannot switch back to the read-only path +unless mount point explicitly names a volume with a B<.readonly> +extension. (Cellular mount points are an important exception to +this rule, as explained in the following discussion. + +=back + +There are three types of mount points, each appropriate for a +different purpose because of the manner in which the Cache Manager +interprets them. + +=over + +=item * + +When the Cache Manager crosses a I mount point, it obeys all +three of the mount point traversal rules previously described. To +create a regular mount point, include only the required B<-dir> and +B<-vol> arguments to the C command. + +=over + +=item B: + +A regular mount point does not force the Cache Manager always to +access read-only volumes (it is explicitly not a "read-only mount +point"). If a volume is not replicated, the third traversal rule means +that the Cache Manager still accesses the read/write volume when that +is the only type available. However, if the Cache Manager is to access +the read-only version of a replicated volume named by a regular mount +point, all volumes that are mounted above it in the pathname must also +be replicated. + +=back + +=item * + +When the Cache Manager crosses a I mount point, it +attempts to access only the volume version named in the mount +point. If the volume name is the base (read/write) form, without a +B<.readonly> or B<.backup> extension, the Cache Manager accesses the +read/write version of the volume, even if it is replicated. In +other words, the Cache Manager disregards the second mount point +traversal rule when crossing a read/write mount point: it switches +to the read/write path through the filespace. + +To create a read/write mount point, include the B<-rw> flag on the C command. It is conventional to create only one read/write +mount point in a cell's filespace, using it to mount the cell's +B volume just below the AFS filespace root (by convention, +B.I). See the IBM AFS Quick Beginnings for instructions +and the chapter about volume management in the IBM AFS +Administration Guide for further discussion. + +Creating a read/write mount point for a read-only or backup volume +is acceptable, but unnecessary. The first rule of mount point +traversal already specifies that the Cache Manager accesses them +if the volume name in a regular mount point has a B<.readonly> or +B<.backup> extension. + +=item * + +When the Cache Manager crosses a I mount point, it accesses +the indicated volume in the specified cell, which is normally a +foreign cell. (If the mount point does not name a cell along with +the volume, the Cache Manager accesses the volume in the cell +where the mount point resides.) The Cache Manager disregards the +third mount point traversal rule when crossing a regular cellular +mount point: it accesses a read-only version of the volume if it +is replicated, even if the volume that houses the mount point is +read/write. Switching to the read-only path in this way is +designed to avoid imposing undue load on the file server machines +in foreign cells. + +To create a regular cellular mount point, include the B<-cell> +argument on the C command. It is conventional to create +cellular mount points only at the second level in a cell's +filespace, using them to mount foreign cells' B volumes +just below the AFS filespace root (by convention, at +BI). The mount point enables local users to +access the foreign cell's filespace, assuming they have the +necessary permissions on the ACL of the volume's root directory +and that there is an entry for the foreign cell in each local +client machine's B file. In the output of +the C command, the cell name and a colon (:) appear +between the initial number sign and the volume name in a regular +cellular mount point name. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-dir> I + +Names the directory to create as a mount point. The directory +must not already exist. Relative pathnames are interpreted with +respect to the current working directory. + +Specify the read/write path to the directory, to avoid the +failure that results from attempting to create a new mount +point in a read-only volume. By convention, the read/write path +is indicated by placing a period before the cell name at the +pathname's second level (for example, B). For +further discussion of the concept of read/write and read-only +paths through the filespace, see the L section of +this reference page. + +=item B<-vol> I + +Specifies the name or volume ID number of the volume to mount. +If appropriate, add the C<.readonly> or C<.backup> extension to the +name, or specify the appropriate volume ID number. + +=item B<-cell> I + +Names the cell in which the volume resides (creates a cellular +mount point). Provide the fully qualified domain name, or a +shortened form that disambiguates it from the other cells +listed in the local B file. + +If this argument is omitted, no cell indicator appears in the +mount point. When the Cache Manager interprets it, it assumes +that the volume named in the mount point resides in the same +cell as the volume that houses the mount point. + +=item B<-rw> + +Creates a read/write mount point. Omit this flag to create a +regular mount point. + +=item B<-fast> + +Prevents the Volume Location (VL) Server from checking that the +volume has a VLDB entry and printing a warning message if it +does not. Whether or not this flag is included, the File Server +creates the mount point even when the volume has no VLDB entry. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command creates a regular mount point, mounting the +volume B at B: + + cd /afs/abc.com/usr + + fs mkmount -dir smith -vol user.smith + +The following commands create a read/write mount point and a regular +mount point for the ABC Corporation cell's C volume in that +cell's file tree. The second command follows the convention of putting +a period at the beginning of the read/write mount point's name. + + fs mkmount -dir /afs/abc.com -vol root.cell + + fs mkmount -dir /afs/.abc.com -vol root.cell -rw + +The following command mounts the State University cell's C +volume in the ABC Corporation cell's file tree, creating a regular +cellular mount point called B. When a ABC Corporation +Cache Manager encounters this mount point, it crosses into the State +University cell on a read-only path. + + fs mkmount -dir /afs/stateu.edu -vol root.cell -c stateu.edu + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) and B (B) permissions on +the ACL of the directory that is to house the mount point. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_newcell.pod b/doc/man-pages/pod/fs_newcell.pod new file mode 100644 index 0000000000..a84f13d056 --- /dev/null +++ b/doc/man-pages/pod/fs_newcell.pod @@ -0,0 +1,112 @@ +=head1 NAME + +fs newcell - Changes the kernel-resident list of a cell's database server machines + +=head1 SYNOPSIS + +fs newcell B<-name> I B<-servers> I [I ...] +[B<-linkedcell> I] [B<-help>] + +fs n B<-n> I B<-s> I [I ...] [B<-l> I] [B<-h>] + +=head1 DESCRIPTION + +The C command removes the Cache Manager's kernel-resident +list of database server machines for the cell specified by the B<-name> +argument and replaces it with the database server machines named by +the B<-servers> argument. + +Each time the machine reboots, the Cache Manager constructs the kernel +list of cells and database server machines by reading the local +B file. This command does not change the +B file, so any changes made with it persist only until the +next reboot, unless the issuer also edits the file. The output of the +C command reflects changes made with this command, because +that command consults the kernel-resident list rather than the +B file. + +This command can introduce a completely new cell into the +kernel-resident list, but cannot make a cell inaccessible (it is not +possible to remove a cell's entry from the kernel-resident list by +providing no values for the B<-server> argument). To make a cell +inaccessible, remove its entry from the B file and reboot the +machine. + +If the B<-name> argument names a DCE cell, then the B<-servers> argument +names DFS Fileset Location (FL) Server machines. The B<-linkedcell> +argument specifies the name of the AFS cell to link to a DCE cell for +the purpose of DFS fileset location. Refer to the IBM AFS/DFS +Migration Toolkit Administration Guide and Reference for more +information on linking AFS clients to DCE cells using this command or +by editing the B file. + +=head1 OPTIONS + +=over 4 + +=item B<-name> I + +Specifies the fully-qualified cell name of the AFS or DCE cell. + +=item B<-servers> I [I ...] + +Specifies the fully-qualified hostnames of all AFS database +server machines or DFS Fileset Location (FL) Server machines +for the cell named by the B<-name> argument. If FL Server machines +are specified, the local machine must be running the AFS/DFS +Migration Toolkit Protocol Translator. + +=item B<-linkedcell> I + +Specifies the name of the AFS cell to link to a DCE cell for +the purpose of DFS fileset location. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example changes the machine's kernel-resident list of +database server machines for the ABC Corporation cell to include the +machines B and B: + + fs newcell -name abc.com -servers db1.abc.com db2.abc.com + +The following example links the DCE cell B to the AFS cell +B. The AFS client contacts the Fileset Location (FL) servers +B and B for fileset location information +as it interprets a DFS pathname. + + fs newcell -name dce.abc.com -servers db1.dce.abc.com db2.dce.abc.com \ + -linkedcell abc.com + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +Some commands, such as the C command, work correctly only when the +information is accurate for a cell in both the B file and the +kernel-resident list. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +IBM AFS/DFS Migration Toolkit Administration Guide and Reference, +IBM AFS/DFS Migration Toolkit Administration Installation and Configuration Guide + +=cut diff --git a/doc/man-pages/pod/fs_quota.pod b/doc/man-pages/pod/fs_quota.pod new file mode 100644 index 0000000000..f8a8f842c0 --- /dev/null +++ b/doc/man-pages/pod/fs_quota.pod @@ -0,0 +1,85 @@ +=head1 NAME + +fs quota - Displays the percentage of quota used in the volume containing a +directory or file + +=head1 SYNOPSIS + +fs quota [B<-path> I [I ...]] [B<-help>] + +fs q [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the percent of quota consumed in the +volume that contains each specified directory or file. + +To display more detailed information about the volume and the +partition it resides on, use the C and C commands. + +To set volume quota, use the C or C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each file or directory for which to display the quota +consumed in its parent volume. Partial pathnames are +interpreted relative to the current working directory, which is +also the default value if this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output reports the percent of volume quota used, in the following +format: + +I% of quota used. + +=head1 EXAMPLES + +The following command lists the percent quota used of the volume +housing the current working directory: + + fs quota + 17% of quota used. + +The following command lists the percent quota used of both the volume +housing the current working directory's parent directory and the +volume housing the directory B: + + fs quota -path .. B.com/usr/smith + 43% of quota used. + 92% of quota used. + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the root +directory of the volume that houses the file or directory named by the +B<-path> argument, and on the ACL of each directory that precedes it in +the pathname. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_rmmount.pod b/doc/man-pages/pod/fs_rmmount.pod new file mode 100644 index 0000000000..8749c9660f --- /dev/null +++ b/doc/man-pages/pod/fs_rmmount.pod @@ -0,0 +1,68 @@ +=head1 NAME + +fs rmmount - Removes a mount point + +=head1 SYNOPSIS + +fs rmmount B<-dir> I [I ...] [B<-help>] + +fs rm B<-d> I [I ...] [B<-h>] + +=head1 DESCRIPTION + +The C command removes the mount point named by the B<-dir> +argument from the file system. The corresponding volume remains on its +host partition or partitions, but is inaccessible if there are no +other mount points for it. + +=head1 OPTIONS + +=over 4 + +=item B<-dir> I [I ...] + +Names the mount point to delete from the file system. The last +element in the pathname must be an actual name, not a shorthand +notation such as "dot" (.) or "dot dot" (..). + +Specify the read/write path to the directory, to avoid the +failure that results from attempting to delete a mount point +from a read-only volume. By convention, the read/write path is +indicated by placing a period before the cell name at the +pathname's second level (for example, B). For +further discussion of the concept of read/write and read-only +paths through the filespace, see the L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command removes the mount points B and B from +the current working directory (the B directory). + + fs rmmount jones terry + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the ACL of the +directory that houses each mount point. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_setacl.pod b/doc/man-pages/pod/fs_setacl.pod new file mode 100644 index 0000000000..5b68e9c465 --- /dev/null +++ b/doc/man-pages/pod/fs_setacl.pod @@ -0,0 +1,293 @@ +=head1 NAME + +fs setacl - Sets the ACL for a directory + +=head1 SYNOPSIS + +fs setacl B<-dir> I [I ...] B<-acl> I [I ...] +[B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>] + +fs sa B<-d> I [I ...] B<-a> I [I ...] +[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>] + +fs seta B<-d> I [I ...] B<-a> I [I ...] +[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>] + +=head1 DESCRIPTION + +The C command adds the access control list (ACL) entries +specified with the B<-acl> argument to the ACL of each directory named by +the B<-dir> argument. + +If the B<-dir> argument designates a pathname in DFS filespace (accessed +via the AFS/DFS Migration Toolkit Protocol Translator), it can be a +file as well as a directory. The ACL must already include an entry for +B, however. For more details, refer to the IBM AFS/DFS +Migration Toolkit Administration Guide and Reference. + +Only user and group entries are acceptable values for the B<-acl> +argument. Do not place machine entries (IP addresses) directly on an +ACL; instead, make the machine entry a group member and place the +group on the ACL. + +To completely erase the existing ACL before adding the new entries, +provide the B<-clear> flag. To add the specified entries to the Negative +rights section of the ACL (deny rights to specified users or groups), +provide the B<-negative> flag. + +To display an ACL, use the C command. To copy an ACL from one +directory to another, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-dir> I [I ...] + +Names each AFS directory, or DFS directory or file, for which +the set the ACL. Partial pathnames are interpreted relative to +the current working directory. + +Specify the read/write path to each directory (or DFS file), to +avoid the failure that results from attempting to change a +read-only volume. By convention, the read/write path is +indicated by placing a period before the cell name at the +pathname's second level (for example, B). For +further discussion of the concept of read/write and read-only +paths through the filespace, see the L reference page. + +=item B<-acl> I [I ...] + +Defines a list of one or more ACL entries, each a pair that +names + +=over + +=item * + +A user name or group name as listed in the Protection +Database + +=item * + +One or more ACL permissions, indicated either by combining +the individual letters or by one of the four acceptable +shorthand words + +=back + +in that order, separated by a space (thus every instance of +this argument has two parts). The accepted AFS abbreviations +and shorthand words, and the meaning of each, are as follows: + +=over + +=item B + +(B): change the entries on the ACL + +=item B + +(B): remove files and subdirectories from the +directory or move them to other directories + +=item B + +(B): add files or subdirectories to the directory by +copying, moving or creating + +=item B + +(B): set read locks or write locks on the files in the +directory + +=item B + +(B): list the files and subdirectories in the +directory, stat the directory itself, and issue the C command to examine the directory's ACL + +=item B + +(B): read the contents of files in the directory; +issue the C command to stat the elements in the +directory + +=item B + +(B): modify the contents of files in the directory, +and issue the UNIX C command to change their mode +bits + +=item B + +Have no default meaning to the AFS server processes, but +are made available for applications to use in controlling +access to the directory's contents in additional ways. +The letters must be uppercase. + +=item B + +Equals all seven permissions (B). + +=item B + +No permissions. Removes the user/group from the ACL, but +does not guarantee they have no permissions if they +belong to groups that remain on the ACL. + +=item B + +Equals the B (B) and B (B) permissions. + +=item B + +Equals all permissions except B (B), that is, +B. + +=back + +It is acceptable to mix entries that combine the individual +letters with entries that use the shorthand words, but not use +both types of notation within an individual pairing of user or +group and permissions. + +To learn the proper format and acceptable values for DFS ACL +entries, see the IBM AFS/DFS Migration Toolkit Administration +Guide and Reference. + +=item B<-clear> + +Removes all existing entries on each ACL before adding the +entries specified with the B<-acl> argument. + +=item B<-negative> + +Places the specified ACL entries in the C section +of each ACL, explicitly denying the rights to the user or +group, even if entries on the accompanying C +section of the ACL grant them permissions. + +This argument is not supported for DFS files or directories, +because DFS does not implement negative ACL permissions. + +=item B<-id> + +Places the ACL entries on the Initial Container ACL of each DFS +directory, which are the only file system objects for which +this flag is supported. + +=item B<-if> + +Places the ACL entries on the Initial Object ACL of each DFS +directory, which are the only file system objects for which +this flag is supported. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example adds two entries to the C section of +the current working directory's ACL: the first entry grants B (B) +and B (B) permissions to the group B, while the other +(using the B shorthand) gives all permissions except B +(B) to the user B. + + fs setacl -dir . -acl pat:friends rl smith write + + fs listacl -path . + Access list for . is + Normal rights: + pat:friends rl + smith rlidwk + +The following example includes the B<-clear> flag, which removes the +existing permissions (as displayed with the C command) from +the current working directory's B subdirectory and replaces them +with a new set. + + fs listacl -dir reports + Access list for reports is + Normal rights: + system:authuser rl + pat:friends rlid + smith rlidwk + pat rlidwka + Negative rights: + terry rl + + fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl + + fs listacl -dir reports + Access list for reports is + Normal rights: + system:anyuser rl + smith rlidwk + pat rlidwka + +The following example use the B<-dir> and B<-acl> switches because it sets +the ACL for more than one directory (both the current working +directory and its public subdirectory). + + fs setacl -dir . public -acl pat:friends rli + + fs listacl -path . public + Access list for . is + Normal rights: + pat rlidwka + pat:friends rli + Access list for public is + Normal rights: + pat rlidwka + pat:friends rli + +=head1 PRIVILEGE REQUIRED + +The issuer must have the B (B) permission on the directory's +ACL; the directory's owner and the members of the +B group have the right implicitly, even if it does +not appear on the ACL. + +=head1 CAVEATS + +If the ACL already grants certain permissions to a user or group, the +permissions specified with the C command replace the existing +permissions, rather than being added to them. + +Setting negative permissions is generally unnecessary and not +recommended. Simply omitting a user or group from the Normal rights +section of the ACL is normally adequate to prevent access. In +particular, note that it is futile to deny permissions that are +granted to members of the B group on the same ACL; the +user needs only to issue the C command to receive the denied +permissions. + +When including the B<-clear> option, be sure to reinstate an entry for +each directory's owner that includes at least the B (B) +permission. Without that permission, it is impossible to resolve the +"dot" ( . ) and "dot dot" ( .. ) shorthand from within the directory. +(The directory's owner does implicitly have the B [B] +permission even on a cleared ACL, but must know to use it to add other +permissions.) + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +IBM_AFS/DFS_Migration Toolkit_Administration Guide_and Reference + +=cut diff --git a/doc/man-pages/pod/fs_setcachesize.pod b/doc/man-pages/pod/fs_setcachesize.pod new file mode 100644 index 0000000000..86dc511547 --- /dev/null +++ b/doc/man-pages/pod/fs_setcachesize.pod @@ -0,0 +1,105 @@ +=head1 NAME + +fs setcachesize - Sets the size of the disk cache + +=head1 SYNOPSIS + +fs setcachesize [B<-blocks> I reset)>] +[B<-reset>] [B<-help>] + +fs setca [B<-b> I reset)>] [B<-r>] [B<-h>] + +fs cachesize [B<-b> I reset)>] [B<-r>] [B<-h>] + +fs ca [B<-b> I reset)>] [B<-r>] [B<-h>] + +=head1 DESCRIPTION + +The C command changes the number of kilobyte blocks of +local disk space available to the Cache Manager for its data cache, on +machines that use a disk cache. The command is not operative on +machines that use a memory cache. + +To return the cache size to the default value specified in the third +field of the local B file, provide a value of B<0> +to the B<-blocks> argument. + +To return the cache size to the value set when the machine was last +rebooted, use the B<-reset> flag instead of the B<-blocks> argument. This is +normally the amount specified in the B file, unless the +B<-blocks> argument was included on the C command to override the +B value. + +To display the current cache size and amount of cache in use, for both +disk and memory caches, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-blocks> I reset)> + +Specifies the number of one-kilobyte blocks of disk space +available for the Cache Manager to devote to the cache. Provide +a value of B<0> to set cache size to the default specified in the +B file. + +=item B<-reset> + +Returns the cache size to the value set when the machine was +last booted. This agrees with the value in the B file +unless the B<-blocks> argument was used on the C command. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command sets the disk cache size to 25000 kilobyte +blocks. + + fs setcachesize -blocks 25000 + +Both of the following commands reset the disk cache size to the value +in the B file, assuming that the B<-blocks> argument to the C +command was not used. + + fs setcachesize -blocks 0 + + fs setcachesize -reset + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +This command is not operative on machines using a memory cache, and +results in an error message. To change memory cache size, edit the +B file and reboot, or reboot and provide the B<-blocks> argument +to the C command. + +On machines using a disk cache, do not set the cache size to exceed +85% to 90% of the actual disk space available for the cache directory. +The cache implementation itself requires a small amount of space on +the partition. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_setcell.pod b/doc/man-pages/pod/fs_setcell.pod new file mode 100644 index 0000000000..16bcccdf6f --- /dev/null +++ b/doc/man-pages/pod/fs_setcell.pod @@ -0,0 +1,104 @@ +=head1 NAME + +fs setcell - Allows or disallows running of setuid programs from specified cells + +=head1 SYNOPSIS + +fs setcell B<-cell> I [I ...] [B<-suid>] [B<-nosuid>] [B<-help>] + +fs setce B<-c> I [I ...] [B<-s>] [B<-n>] [B<-h>] + +=head1 DESCRIPTION + +The C command sets whether the Cache Manager allows programs +(and other executable files) from each cell named by the B<-cell> +argument to run with setuid permission. By default, the Cache Manager +allows programs from its home cell to run with setuid permission, but +not programs from any foreign cells. A program belongs to the same +cell as the file server machine that houses the volume in which the +program's binary file resides, as specified in the file server +machine's B file. The Cache Manager determines its +own home cell by reading the B file at +initialization. + +To enable programs from each specified cell to run with setuid +permission, include the B<-suid> flag. To prohibit programs from running +with setuid permission, include the B<-nosuid> flag, or omit both flags. + +The C command directly alters a cell's setuid status as +recorded in kernel memory, so rebooting the machine is unnecessary. +However, non-default settings do not persist across reboots of the +machine unless the appropriate C command appears in the +machine's AFS initialization file. + +To display a cell's setuid status, issue the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-cell> I [I ...] + +Names each cell for which to set setuid status. Provide the +fully qualified domain name, or a shortened form that +disambiguates it from the other cells listed in the local +B file. + +=item B<-suid> + +Allows programs from each specified cell to run with setuid +privilege. Provide it or the B<-nosuid> flag, or omit both flags +to disallow programs from running with setuid privilege. + +=item B<-nosuid> + +Prevents programs from each specified cell from running with +setuid privilege. Provide it or the B<-suid> flag, or omit both +flags to disallow programs form running with setuid privilege. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command enables executable files from the State +University cell to run with setuid privilege on the local machine: + + fs setcell -cell stateu.edu -suid + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +AFS does not recognize effective UID: if a setuid program accesses AFS +files and directories, it does so using the current AFS identity of +the AFS user who initialized the program, not of the program's owner. +Only the local file system recognizes effective UID. + +Only members of the B group can turn on the setuid +mode bit on an AFS file or directory. + +When the setuid mode bit is turned on, the UNIX C command displays +the third user mode bit as an s instead of an x. However, the s does +not appear on an AFS file or directory unless setuid permission is +enabled for the cell in which the file resides. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_setclientaddrs.pod b/doc/man-pages/pod/fs_setclientaddrs.pod new file mode 100644 index 0000000000..597870fb0b --- /dev/null +++ b/doc/man-pages/pod/fs_setclientaddrs.pod @@ -0,0 +1,122 @@ +=head1 NAME + +fs setclientaddrs - Sets the client interfaces to register with the File Server + +=head1 SYNOPSIS + +fs setclientaddrs [B<-address> I [I ...]] [B<-help>] + +fs setcl [B<-a> I [I ...]] [B<-h>] + +fs sc [B<-a> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command defines the IP addresses of the +interfaces that the local Cache Manager registers with a File Server +when first establishing a connection to it. + +The File Server uses the addresses when it initiates a remote +procedure call (RPC) to the Cache Manager (as opposed to responding to +an RPC sent by the Cache Manager). There are two common circumstances +in which the File Server initiates RPCs: when it breaks callbacks and +when it pings the client machine to verify that the Cache Manager is +still accessible. + +The list of interfaces specified with this command replaces the list +that the Cache Manager constructs and records in kernel memory as it +initializes. At that time, if the file B exists on +the client machine's local disk, the Cache Manager uses its contents +as the basis for the list of interfaces addresses. If the file does +not exist, the Cache Manager instead uses the network interfaces +configured with the operating system. It then removes from the list +any address included in the local B file. It +records the final list in kernel memory. (An administrator must create +the B and B files; there are no default versions of +them.) + +If an RPC to that interface fails, the File Server simultaneously +sends RPCs to all of the other interfaces in the list, to learn which +of them are still available. Whichever interface replies first is the +one to which the File Server then sends pings and RPCs to break +callbacks. + +To list the interfaces that the Cache Manager is currently registering +with File Servers, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-address> I [I ...] + +Specifies each IP address to place in the list of interfaces, +in dotted decimal format. Hostnames are not acceptable. +Separate each address with one or more spaces. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The message: + +Adding I + +confirms that each new interface was added to the Cache Manager's +list. The address appears in hexadecimal format to match the notation +used in the File Server log, B. + +=head1 EXAMPLES + +The following example sets the two interfaces that the Cache Manager +registers with File Servers. + + fs setclientaddrs 191.255.105.68 191.255.108.84 + Adding 0xbfff6944 + Adding 0xbfff6c54 + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +The list specified with this command persists in kernel memory only +until the client machine reboots. To preserve it across reboots, +either list the interfaces in the local B file, or +place the appropriate C command in the machine's AFS +initialization script. + +Changes made with this command do not propagate automatically to File +Servers to which the Cache Manager has already established a +connection. To force such File Servers to use the revised list, either +reboot each file server machine, or change the B file and reboot +the client machine. + +The C command interpreter verifies that each of the addresses +specified as a value for the B<-address> argument is actually configured +with the operating system on the client machine. If it is not, the +command fails with an error message that marks the address as a +Nonexistent interface. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_setquota.pod b/doc/man-pages/pod/fs_setquota.pod new file mode 100644 index 0000000000..09c0447120 --- /dev/null +++ b/doc/man-pages/pod/fs_setquota.pod @@ -0,0 +1,90 @@ +=head1 NAME + +fs setquota - Sets the maximum quota for the volume containing a file or directory + +=head1 SYNOPSIS + +fs setquota [B<-path> I] B<-max> I [B<-help>] + +fs setq [B<-p> I] B<-m> I [B<-h>] + +fs sq [B<-p> I] B<-m> I [B<-h>] + +=head1 DESCRIPTION + +The C command sets the quota (maximum possible size) of the +read/write volume that contains the directory or file named by the +B<-path> argument. + +To set the quota on multiple volumes at the same time, use the C command. + +To display a volume's quota, use the C, C or C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I + +Names the directory or file for which to set the host volume's +quota. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if +this argument is omitted. + +Specify the read/write path to the file or directory, to avoid +the failure that results from attempting to change a read-only +volume. By convention, the read/write path is indicated by +placing a period before the cell name at the pathname's second +level (for example, B). For further discussion of +the concept of read/write and read-only paths through the +filespace, see the L reference page. + +=item B<-max> I + +Sets the maximum amount of file server disk space the volume +can occupy. Specify the number of one-kilobyte blocks as a +positive integer (B<1024> is one megabyte). A value of B<0> sets an +unlimited quota, but the size of the disk partition that houses +the volume places an absolute limit on the volume's size. + +If the B<-path> argument is omitted (to set the quota of the +volume housing the current working directory), the B<-max> switch +must be included with this argument. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command imposes a maximum quota of 3000 kilobytes on the +volume that houses the B directory: + + fs setquota -path /afs/abc.com/usr/smith -max 3000 + +=head1 PRIVILEGE REQUIRED + +The issuer must belong to the B group. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_setserverprefs.pod b/doc/man-pages/pod/fs_setserverprefs.pod new file mode 100644 index 0000000000..115208fad4 --- /dev/null +++ b/doc/man-pages/pod/fs_setserverprefs.pod @@ -0,0 +1,320 @@ +=head1 NAME + +fs setserverprefs - Sets the Cache Manager's preference ranks for file server or VL Server +machines + +=head1 SYNOPSIS + +fs setserverprefs [B<-servers> I [I ...]] +[B<-vlservers> I [I ...]] +[B<-file> I] [B<-stdin>] [B<-help>] + +fs sets [B<-se> I [I ...]] [B<-vl> I^ ++] +[B<-f> I] [B<-st>] [B<-h>] + +fs sp [B<-se> I [I ...]] [B<-vl> I [I ...]] + +[B<-f> I] [B<-st>] [B<-h>] + +=head1 DESCRIPTION + +The C command sets the local Cache Manager's +preference ranks for one or more file server machine interfaces or, if +the B<-vlserver> argument is provided, for Volume Location (VL) Server +machines. For file server machines, the numerical ranks determine the +order in which the Cache Manager attempts to contact the interfaces of +machines that are housing a volume. For VL Server machines, the ranks +determine the order in which the Cache Manager attempts to contact a +cell's VL Servers when requesting VLDB information. + +The L reference page explains how the Cache Manager +uses preference ranks when contacting file server machines or VL +Server machines. The following paragraphs explain how the Cache +Manager calculates default ranks, and how to use this command to +change the defaults. + +=head2 Calculation of Default Preference Ranks + +The Cache Manager stores a preference rank in kernel memory as a +paired IP address and numerical rank. If a file server machine is +multihomed, the Cache Manager assigns a distinct rank to each of the +machine's addresses (up to the number of addresses that the VLDB can +store per machine, which is specified in the IBM AFS Release Notes). +Once calculated, a rank persists until the machine reboots, or until +this command is used to change it. + +The Cache Manager sets default VL Server preference ranks as it +initializes, randomly assigning a rank from the range 10,000 to 10,126 +to each of the machines listed in the local B +file. Machines from different cells can have the same rank, but this +does not present a problem because the Cache Manager consults only one +cell's ranks at a time. + +The Cache Manager sets default preference ranks for file server +machine as it fetches volume location information from the VLDB. Each +time it learns about file server machine interfaces for which it has +not already set ranks, it assigns a rank to each interface. If the +local client machine has only one IP address, the Cache Manager +compares it to the server interface's IP address and sets a rank +according to the following algorithm. If the client machine is +multihomed, the Cache Manager applies the algorithm to each of the +client machine's addresses and assigns to the file server machine +interface the lowest rank that results. + +=over + +=item * + +If the local machine is a file server machine, the base rank for +each of its interfaces is 5,000. + +=item * + +If the file server machine interface is on the same subnetwork as +the client interface, its base rank is 20,000. + +=item * + +If the file server machine interface is on the same network as the +client interface, or is at the distant end of a point-to-point +link with the client interface, its base rank is 30,000. + +=item * + +If the file server machine interface is on a different network +than the client interface, or the Cache Manager cannot obtain +network information about it, its base rank is 40,000. + +=back + +After assigning a base rank to a file server machine interface, the +Cache Manager adds to it a number randomly chosen from the range 0 +(zero) to 14. As an example, a file server machine interface in the +same subnetwork as the local machine receives a base rank of 20,000, +but the Cache Manager records the actual rank as an integer between +20,000 and 20,014. This process reduces the number of interfaces that +have exactly the same rank. As with VL Server machine ranks, it is +possible for file server machine interfaces from foreign cells to have +the same rank as interfaces in the local cell, but this does not +present a problem. Only the relative ranks of the interfaces that +house a given volume are relevant, and AFS only supports storage of a +volume in one cell at a time. + +=head2 Setting Non-default Preference Ranks + +Use the C command to reset an existing preference +rank, or to set the initial rank of a file server machine interface or +VL Server machine for which the Cache Manager has no rank. To make a +rank persist across a reboot of the local machine, place the +appropriate C command in the machine's AFS +initialization file. + +Specify each preference rank as a pair of values separated by one or +more spaces: + +=over + +=item * + +The first member of the pair is the fully-qualified hostname (for +example, B), or the IP address in dotted decimal format, +of a file server machine interface or VL Server machine + +=item * + +The second member of the pair is an integer. The possible ranks +range from B<1> through B<65535>. + +=back + +As with default ranks, the Cache Manager adds a randomly chosen +integer to a rank specified by this command. For file server machine +interfaces, the integer is from the range 0 (zero) to 14; for VL +Server machines, it is from the range 0 (zero) to 126. For example, if +the administrator assigns a rank of 15,000 to a file server machine +interface, the Cache Manager stores an integer between 15,000 to +15,014. + +There are several ways to provide ranks for file server machine +interfaces (but not for VL Server machines): + +=over + +=item * + +On the command line, following the B<-servers> argument. + +=item * + +In a file named by the B<-file> argument. Place each pair on its own +line in the file. Directing the output from the C +command to a file automatically generates a file with the proper +format. + +=item * + +Via the standard input stream, by providing the B<-stdin> flag. This +method enables the issuer to feed in values directly from a +program or script that generates preference ranks by using an +algorithm appropriate to the local cell. The AFS distribution does +not include such programs or scripts. + +=back + +When setting file server machine preference ranks, it is legal to +combine the B<-servers>, B<-file>, and B<-stdin> options on a single command +line. If different options specify a different rank for the same +interface, the Cache Manager stores and uses the rank assigned with +the B<-servers> argument. + +The B<-vlservers> argument is the only way to assign VL Server machine +ranks. It can be combined with one or more of the B<-servers>, B<-file>, and +B<-stdin> options, but the Cache Manager applies the values provided for +those options to file server machine ranks only. + +The C command interpreter does not verify hostnames or IP addresses, +and so assigns preference ranks to invalid machine names or addresses. +The Cache Manager never uses such ranks unless the same incorrect +information is in the VLDB. + +=head1 OPTIONS + +=over 4 + +=item B<-servers> I [I ...] + +Specifies one or more file server machine preference ranks. +Each rank pairs the fully-qualified hostname or IP address (in +dotted decimal format) of a file server machine's interface +with an integer rank, separated by one or more spaces; also +separate each pair with one or more spaces. Acceptable values +for the rank range from B<1> through B<65521>; a lower value +indicates a greater preference. Providing ranks outside this +range can have unpredictable results. Providing a value no +larger than B<65521> guarantees that the rank does not exceed the +maximum possible value of 65,535 even if the largest random +factor (14) is added. + +This argument can be combined with the B<-file> argument, B<-stdin> +flag, or both. If more than one of the arguments sets a rank +for the same interface, the rank set by this argument takes +precedence. It can also be combined with the B<-vlservers> +argument, but does not interact with it. + +=item B<-vlservers> I [I ...] + +Specifies one or more VL Server preference ranks. Each rank +pairs the fully-qualified hostname or IP address (in dotted +decimal format) of a VL Server machine with an integer rank, +separated by one or more spaces; also separate each pair with +one or more spaces. Acceptable values for the rank range from B<1> +through B<65521>; a lower value indicates a greater preference. +Providing ranks outside this range can have unpredictable +results. Providing a value no larger than B<65521> guarantees that +the rank does not exceed the maximum possible value of 65,535 +even if the largest random factor (14) is added. + +This argument can be combined with the B<-servers> argument, B<-file> +argument, B<-stdin> flag, or any combination of the three, but +does not interact with any of them. They apply only to file +server machine ranks. + +=item B<-file> I + +Specifies the full pathname of a file from which to read pairs +of file server machine interfaces and their ranks, using the +same notation and range of values as for the B<-servers> argument. +In the file, place each pair on its own line and separate the +two parts of each pair with one or more spaces. + +This argument can be combined with the B<-servers> argument, +B<-stdin> flag, or both. If more than one of the arguments sets a +rank for the same interface, the rank set by the B<-server> +argument takes precedence. It can also be combined with the +B<-vlservers> argument, but does not interact with it. + +=item B<-stdin> + +Reads pairs of file server machine interface and integer rank +from the standard input stream. The intended use is to accept +input piped in from a user-defined program or script that +generates ranks in the appropriate format, but it also accepts +input typed to the shell. Format the interface and rank pairs +as for the B<-file> argument. If typing at the shell, type +BCtrl-dE> after the final newline to complete the input. + +This argument can be combined with the B<-servers> argument, the +B<-file> argument, or both. If more than one of the arguments sets +a rank for the same interface, the rank set by the B<-server> +argument takes precedence. It can also be combined with the +B<-vlservers> argument, but does not interact with it. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command sets the Cache Manager's preference ranks for +the file server machines named B and B, the latter +of which is specified by its IP address, 192.12.105.100. The machines +reside in another subnetwork of the local machine's network, so their +default base rank is 30,000. To increase the Cache Manager's +preference for these machines, the issuer assigns a rank of B<25000>, to +which the Cache Manager adds an integer in the range from 0 to 15. + + fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 + +The following command uses the B<-servers> argument to set the Cache +Manager's preference ranks for the same two file server machines, but +it also uses the B<-file> argument to read a collection of preference +ranks from a file that resides in the local file B: + + fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \ + -file /etc/fs.prefs + +The B file has the following contents and format: + + 192.12.108.214 7500 + 192.12.108.212 7500 + 138.255.33.41 39000 + 138.255.33.34 39000 + 128.0.45.36 41000 + 128.0.45.37 41000 + +The following command uses the B<-stdin> flag to read preference ranks +from the standard input stream. The ranks are piped to the command +from a program, B, which was written by the issuer to +calculate preferences based on values significant to the local cell. + + calc_prefs | fs setserverprefs -stdin + +The following command uses the B<-vlservers> argument to set the Cache +Manager's preferences for the VL server machines named B, +B, and B to base ranks of 1, 11000, and 65521, +respectively: + + fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \ + fs4.abc.com 65521 + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_setvol.pod b/doc/man-pages/pod/fs_setvol.pod new file mode 100644 index 0000000000..be53f75ac0 --- /dev/null +++ b/doc/man-pages/pod/fs_setvol.pod @@ -0,0 +1,106 @@ +=head1 NAME + +fs setvol - Set maximum quota and messages for the volume containing a file or +directory + +=head1 SYNOPSIS + +fs setvol [B<-path> I [I ...]] [B<-max> I] +[B<-offlinemsg> I] [B<-help>] + +fs setv [B<-p> I [I ...]] [B<-ma> I] +[B<-o> I] [B<-h>] + +fs sv [B<-p> I [I ...]] [B<-ma> I] +[B<-o> I] [B<-h>] + +=head1 DESCRIPTION + +The C command sets the quota (maximum possible size) of the +read/write volume that contains each directory or file named by the +B<-path> argument. To associate a message with the volume which then +appears in the output of the C command, include the +B<-offlinemsg> argument. + +To display all of the settings made with this command, use the C command. The C command reports a fileset's quota, +and the C command the percent of quota used. + +To set quota on one volume at a time, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each file or directory for which to set the host volume's +quota and offline message. Partial pathnames are interpreted +relative to the current working directory, which is also the +default value if this argument is omitted. + +Specify the read/write path to the file or directory, to avoid +the failure that results from attempting to change a read-only +volume. By convention, the read/write path is indicated by +placing a period before the cell name at the pathname's second +level (for example, B). For further discussion of +the concept of read/write and read-only paths through the +filespace, see the L reference page. + +=item B<-max> I + +Sets the maximum amount of file server disk space the volume +can occupy. Provide a positive integer to indicate the number +of one-kilobyte blocks (B<1024> is one megabyte). A value of B<0> +sets an unlimited quota, but the size of the disk partition +that houses the volume places an absolute limit on the volume's +size. + +If the B<-path> argument is omitted (so that the command sets the +quota of the volume housing the current working directory), the +B<-max> switch must be provided. + +=item B<-offlinemsg> I + +Associates a message with the volume which then appears in the +output of the C command. Its intended use is to +explain why the volume is currently offline. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command imposes a 6500 kilobyte quota on the volumes +mounted at the home directories B and +B: + + cd /afs/abc.com/usr + + fs setvol -path smith pat -max 6500 + +=head1 PRIVILEGE REQUIRED + +The issuer must belong to the B group. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_storebehind.pod b/doc/man-pages/pod/fs_storebehind.pod new file mode 100644 index 0000000000..bada1cc37d --- /dev/null +++ b/doc/man-pages/pod/fs_storebehind.pod @@ -0,0 +1,231 @@ +=head1 NAME + +fs storebehind - Enables asynchronous writes to the file server + +=head1 SYNOPSIS + +fs storebehind [B<-kbytes> I] +[B<-files> I [I ...]] +[B<-allfiles> I] [B<-verbose>] [B<-help>] + +fs st [B<-k> I] [B<-f> I [I ...]] +[B<-a> I] [B<-v>] [B<-h>] + +=head1 DESCRIPTION + +The C command enables the Cache Manager to perform a +delayed asynchronous write to the File Server when an application +closes a file. By default, the Cache Manager writes all data to the +File Server immediately and synchronously when an application program +closes a file--that is, the B system call does not return until +the Cache Manager has actually transferred the final chunk of the file +to the File Server. This command specifies the number of kilobytes of +a file that can still remain to be written to the File Server when the +Cache Manager returns control to the application. It is useful if +users working on the machine commonly work with very large files, but +also introduces the complications discussed in the L section. + +Set either or both of the following in a single command: + +=over + +=item * + +To set a value that applies to all AFS files manipulated by +applications running on the machine, use the B<-allfiles> argument. +This value is termed the I for the machine, +and persists until the machine reboots. If it is not set, the +default value is zero, indicating that the Cache Manager performs +synchronous writes. + +As an example, the following setting means that when an +application closes a file, the Cache Manager can return control to +the application as soon as no more than 10 kilobytes of the file +remain to be written to the File Server. + + -allfiles 10 + +=item * + +To set a value that applies to one or more individual files, and +overrides the value of the B<-allfiles> argument for them, combine +the B<-kbytes> and B<-files> arguments. The setting persists as long as +there is an entry for the file in the kernel table that the Cache +Manager uses to track certain information about files. In general, +such an entry persists at least until an application closes the +file or exits, but the Cache Manager is free to recycle the entry +if the file is inactive and it needs to free up slots in the +table. To increase the certainty that there is an entry for the +file in the table, issue the C command shortly before +closing the file. + +As an example, the following setting means that when an +application closes either of the files B and B, the +Cache Manager can return control to the application as soon as no +more than a megabyte of the file remains to be written to the File +Server. + + -kbytes 1024 -files bigfile biggerfile + +Note that once an explicit value has been set for a file, the only +way to make it subject to the default store asynchrony once again +is to set B<-kbytes> to that value. In other words, there is no +combination of arguments that automatically makes a file subject +to the default store asynchrony once another value has been set +for the file. + +=back + +To display the settings that currently apply to individual files or to +all files, provide the command's arguments in certain combinations as +specified in the L section of this reference page. + +=head1 OPTIONS + +=over 4 + +=item B<-kbytes> I + +Specifies the number of kilobytes of data from each file named +by the B<-files> argument that can remain to be written to the +file server when the Cache Manager returns control to an +application program that closed the file. The B<-files> argument +is required along with this argument. Provide an integer from +the range B<0> (which reinstates the Cache Manager's default +behavior or writing synchronously) to the maximum AFS file +size. + +=item B<-files> I [I ...] + +Names each file to which the value set with the B<-kbytes> +argument applies. The setting persists as long as there is an +entry for the file in the kernel table that the Cache Manager +uses to track certain information about files. Because closing +a file generally erases the entry, when reopening a file the +only way to guarantee that the setting still applies is to +reissue the command. If this argument is provided without the +B<-kbytes> argument, the command reports the current setting for +the specified files, and the default store asynchrony. + +=item B<-allfiles> I + +Sets the default store asynchrony for the local machine, which +is the number of kilobytes of data that can remain to be +written to the file server when the Cache Manager returns +control to the application program that closed a file. The +value applies to all AFS files manipulated by applications +running on the machine, except those for which settings have +been made with the B<-kbytes> and B<-files> arguments. Provide an +integer from the range B<0> (which indicates the default of +synchronous writes) to the maximum AFS file size. + +=item B<-verbose> + +Produces output confirming the settings made with the +accompanying B<-kbytes> and B<-files> arguments, the B<-allfiles> +argument, or all three. If provided by itself, reports the +current default store asynchrony. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If none of the command's options are included, or if only the B<-verbose> +flag is included, the following message reports the default store +asynchrony (the setting that applies to all files manipulated by +applications running on the local machine and for which not more +specific asynchrony is set). + + Default store asynchrony is x kbytes. + +A value of C<0> (zero) indicates synchronous writes and is the default if +no one has included the B<-allfiles> argument on this command since the +machine last rebooted. + +If the B<-files> argument is provided without the B<-kbytes> argument, the +output reports the value that applies to each specified file along +with the default store asynchrony. If a particular value has +previously been set for a file, the following message reports it: + + Will store up to y kbytes of file asynchronously. + Default store asynchrony is x kbytes. + +If the default store asynchrony applies to a file because no explicit +B<-kbytes> value has been set for it, the message is instead as follows: + + Will store file according to default. + Default store asynchrony is x kbytes. + +If the B<-verbose> flag is combined with arguments that set values +(B<-files> and B<-kbytes>, or B<-allfiles>, or all three), there is a message +that confirms immediately that the setting has taken effect. When +included without other arguments or flags, the B<-verbose> flag reports +the default store asynchrony only. + +=head1 EXAMPLES + +The following command enables the Cache Manager to return control to +the application program that closed the file B when 100 +kilobytes still remain to be written to the File Server. The B<-verbose> +flag produces output that confirms the new setting, and that the +default store asynchrony is zero. + + fs storebehind -kbytes 100 -files test.data -verbose + Will store up to 100 kbytes of test.data asynchronously. + Default store asynchrony is 0 kbytes. + +=head1 PRIVILEGE REQUIRED + +To include the B<-allfiles> argument, the issuer must be logged in as the +local superuser B. + +To include the B<-kbytes> and B<-files> arguments, the issuer must either be +logged in as the local superuser B or have the B (B) permission +on the ACL of each file's directory. + +To view the current settings (by including no arguments, the B<-file> +argument alone, or the B<-verbose> argument alone), no privilege is +required. + +=head1 CAVEATS + +For the following reasons, use of this command is not recommended in +most cases. + +In normal circumstances, an asynchronous setting results in the Cache +Manager returning control to applications earlier than it otherwise +does, but this is not guaranteed. + +If a delayed write fails, there is no way to notify the application, +since the B system call has already returned with a code +indicating success. + +Writing asynchronously increases the possibility that the user will +not notice if a write operation makes the volume that houses the file +exceed its quota. As always, the portion of the file that exceeds the +volume's quota is lost, which prompts a message such as the following: + +C + +To avoid losing data, it is advisable to verify that the volume +housing the file has space available for the amount of data +anticipated to be written. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L + +=cut diff --git a/doc/man-pages/pod/fs_sysname.pod b/doc/man-pages/pod/fs_sysname.pod new file mode 100644 index 0000000000..d14f529929 --- /dev/null +++ b/doc/man-pages/pod/fs_sysname.pod @@ -0,0 +1,94 @@ +=head1 NAME + +fs sysname - Reports or sets the CPU/operating system type + +=head1 SYNOPSIS + +fs sysname [B<-newsys> I] [B<-help>] + +fs sy [B<-n> I] [B<-h>] + +=head1 DESCRIPTION + +The C command sets or displays the local machine's +CPU/operating system type as recorded in kernel memory. The Cache +Manager substitutes the string for the I<@sys> variable which can occur +in AFS pathnames; the IBM AFS Quick Beginnings and IBM AFS +Administration Guide explain how using I<@sys> can simplify cell +configuration. It is best to use it sparingly, however, because it can +make the effect of changing directories unpredictable. + +The command always applies to the local machine only. If issued on an +NFS client machine accessing AFS via the NFS/AFS Translator, the +string is set or reported for the NFS client machine. The Cache +Manager on the AFS client machine serving as the NFS client's NFS/AFS +translator machine stores the value in its kernel memory, and so can +provide the NFS client with the proper version of program binaries +when the user issues commands for which the pathname to the binaries +includes I<@sys>. There is a separate record for each user logged into +the NFS client, which implies that if a user adopts a new identity +(UNIX UID) during a login session on the NFS client--perhaps by using +the UNIX C command--he or she must verify that the correct string is +set for the new identity also. + +=head1 OPTIONS + +=over 4 + +=item B<-newsys> I + +Sets the CPU/operating system indicator string for the local +machine. If this argument is omitted, the output displays the +current setting instead. AFS uses a standardized set of +strings; consult the IBM AFS Quick Beginnings or AFS Release +Notes. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +When the B<-newsys> argument is omitted, the output reports the machine's +system type in the following format: + +Current sysname is 'I' + +=head1 EXAMPLES + +The following example shows the output produced on a Sun SPARCStation +running Solaris 5.7: + + fs sysname + Current sysname is 'sun4x_57' + +The following command defines a machine to be a IBM RS/6000 running +AIX 4.2: + + fs sysname -newsys rs_aix42 + +=head1 PRIVILEGE REQUIRED + +To display the current setting, no privilege is required. To include +the B<-newsys> argument on an AFS client machine, the issuer must be +logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +IBM AFS Quick Beginnings, +IBM AFS Administration Guide + +=cut diff --git a/doc/man-pages/pod/fs_whereis.pod b/doc/man-pages/pod/fs_whereis.pod new file mode 100644 index 0000000000..9bd5750c01 --- /dev/null +++ b/doc/man-pages/pod/fs_whereis.pod @@ -0,0 +1,74 @@ +=head1 NAME + +fs whereis - Reports the name of each file server machine housing a file or +directory + +=head1 SYNOPSIS + +fs whereis [B<-path> I [I ...]] [B<-help>] + +fs whe [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command returns the name of each file server machine +that houses the volume containing each directory or file named by the +B<-path> argument. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each AFS file or directory for which to return the host +file server machine. Partial pathnames are interpreted relative +to the current working directory, which is also the default +value if this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output includes a line for each specified directory or file. It +names the file server machine on which the volume that houses the +specified directory or file resides. A list of multiple machines +indicates that the directory or file is in a replicated volume. + +Machine names usually have a suffix indicating their cell membership. +If the cell is not clear, use the C command to display the +cell in which the directory or file resides. To display the cell +membership of the local machine, use the C command. + +=head1 EXAMPLES + +The following example indicates that volume housing the directory +B resides is replicated on both B and +B: + + fs whereis -path /afs/abc.com + File /afs/abc.com is on hosts fs1.abc.com fs3.abc.com + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_whichcell.pod b/doc/man-pages/pod/fs_whichcell.pod new file mode 100644 index 0000000000..05bf4b3987 --- /dev/null +++ b/doc/man-pages/pod/fs_whichcell.pod @@ -0,0 +1,68 @@ +=head1 NAME + +fs whichcell - Returns the name of the cell to which a file or directory belongs + +=head1 SYNOPSIS + +fs whichcell [B<-path> I [I ...]] [B<-help>] + +fs whi [B<-p> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command returns the name of the cell in which the +volume that houses each indicated directory or file resides. + +To display the file server machine on which the volume housing a +directory or file resides, use the C command. To display +the cell membership of the local machine, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-path> I [I ...] + +Names each AFS file or directory for which to return the cell +membership. Partial pathnames are interpreted relative to the +current working directory, which is also the default value if +this argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output includes a line for each directory or file, naming the cell +to which the volume that houses the directory or file resides. + +=head1 EXAMPLES + +The following example shows that the current working directory resides +in a volume in the ABC Corporation cell: + + fs whichcell + File . lives in cell 'abc.com' + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fs_wscell.pod b/doc/man-pages/pod/fs_wscell.pod new file mode 100644 index 0000000000..1857951b66 --- /dev/null +++ b/doc/man-pages/pod/fs_wscell.pod @@ -0,0 +1,59 @@ +=head1 NAME + +fs wscell - Returns the name of the cell to which a machine belongs + +=head1 SYNOPSIS + +fs wscell [B<-help>] + +fs ws [B<-h>] + +=head1 DESCRIPTION + +The C command returns the name of the local machine's home +cell. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output displays the contents of the local B +file, in the format + +This workstation belongs to cell 'I' + +=head1 EXAMPLES + +The following example results when the C is issued on a +machine in the State University cell: + + fs wscell + This workstation belongs to cell 'stateu.edu' + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace.pod b/doc/man-pages/pod/fstrace.pod new file mode 100644 index 0000000000..a77b028269 --- /dev/null +++ b/doc/man-pages/pod/fstrace.pod @@ -0,0 +1,88 @@ +=head1 NAME + +fstrace - Introduction to the C command suite + +=head1 DESCRIPTION + +The commands in the C command suite are the interface that +system administrators employ to trace Cache Manager operations for +debugging purposes. Examples of Cache Manager operations are fetching +file data or the status information used to produce output for the +UNIX B command. + +The C command interpreter defines an extensive set of Cache +Manager operations as the B I. When the event set is +activated, the Cache Manager writes a message to the B I in +kernel memory each time it performs one of the defined operations. The +log expands only to a defined size (by default, 60 KB), after which it +is overwritten in a circular fashion (new trace messages overwrite the +oldest ones). If an operation of particular interest occurs, the +administrator can afterward display the log on the standard output +stream or write it to a file for later study. For more specific +procedural instructions, see the IBM AFS Administration Guide. + +There are several categories of commands in the C command suite: + +=over + +=item * + +Commands to administer or display information about the trace log: +C, C, C + +=item * + +Commands to set or display the status of the event set: +C and C + +=item * + +A command to display the contents of the trace log: C + +=item * + +Commands to obtain help: C and C + +=back + +=head1 OPTIONS + +All C commands accept the following optional flag. It is listed +in the command descriptions and described in detail here: + +=over 4 + +=item B<-help> + +Prints a command's online help message on the standard output +stream. Do not combine this flag with any of the command's +other options; when it is provided, the command interpreter +ignores all other options, and only prints the help message. + +=back + +=head1 PRIVILEGE REQUIRED + +To issue most C commands, the issuer must be logged on as the +local superuser B on the machine that is generating the trace log. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_apropos.pod b/doc/man-pages/pod/fstrace_apropos.pod new file mode 100644 index 0000000000..85bcc04862 --- /dev/null +++ b/doc/man-pages/pod/fstrace_apropos.pod @@ -0,0 +1,71 @@ +=head1 NAME + +fstrace apropos - Displays each help entry containing a keyword string + +=head1 SYNOPSIS + +fstrace apropos B<-topic> I [B<-help>] + +fstrace ap B<-t> I [B<-h>] + +=head1 DESCRIPTION + +The C command displays the first line of the online help +entry for any C command that contains in its name or short +description the string specified with the B<-topic> argument. + +To display a command's complete syntax, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I + +Specifies the keyword string to match, in lowercase letters +only. If the string is more than a single word, surround it +with double quotes ("") or other delimiters. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of a command's online help entry names it and briefly +describes its function. This command displays the first line for any +C command where the string specified with the B<-topic> argument is +part of the command name or first line. + +=head1 EXAMPLES + +The following command lists all C commands that include the word +B in their names or short descriptions: + + fstrace apropos set + clear: clear logs by logname or by event set + lsset: list available event sets + setlog: set the size of a log + setset: set state of event sets + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_clear.pod b/doc/man-pages/pod/fstrace_clear.pod new file mode 100644 index 0000000000..50ef2d006b --- /dev/null +++ b/doc/man-pages/pod/fstrace_clear.pod @@ -0,0 +1,64 @@ +=head1 NAME + +fstrace clear - Clears the trace log + +=head1 SYNOPSIS + +fstrace clear [B<-set> I [I ...]] [B<-log> I [I ...]] [B<-help>] + +fstrace c [B<-s> I [I ...]] [B<-l> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command erases the contents of the trace log from +kernel memory, but leaves kernel memory allocated for the log. + +=head1 OPTIONS + +=over 4 + +=item B<-set> I [I ...] + +Names the event set for which to clear the associated trace +log. The only acceptable value is B (for which the associated +trace log is B). Provide either this argument or the B<-log> +argument, or omit both to clear the B log by default. + +=item B<-log> I [I ...] + +Names the trace log to clear. The only acceptable value is +B. Provide either this argument or the B<-set> argument, or +omit both to clear the B log by default. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command clears the B trace log on the local machine: + + fstrace clear + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_dump.pod b/doc/man-pages/pod/fstrace_dump.pod new file mode 100644 index 0000000000..ade52c3020 --- /dev/null +++ b/doc/man-pages/pod/fstrace_dump.pod @@ -0,0 +1,248 @@ +=head1 NAME + +fstrace dump - Dumps a trace log + +=head1 SYNOPSIS + +fstrace dump [B<-set> I [I ...]] [B<-follow> I] +[B<-file> I] +[B<-sleep> I] [B<-help>] + +fstrace d [B<-se> I [I ...]] [B<-fo> I] [B<-fi> I] +[B<-sl> I] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the current contents of the B +trace log on the standard output stream or writes it to the file named +by the B<-file> argument. + +To write the log continuously to the standard output stream or to a +file, use the B<-follow> argument. By default, the log's contents are +written out every ten seconds and then automatically cleared. To +change the interval between writes, use the B<-sleep> argument. + +=head1 OPTIONS + +=over 4 + +=item B<-set> I [I ...] + +Names the event set for which to write out the associated trace +log. The only acceptable value is B (for which the associated +trace log is B). Provide either this argument or the B<-follow> +argument, or omit both to write out the B log by default. + +=item B<-follow> I + +Names the trace log to write out continuously at a specified +interval (by default, every ten seconds; use the B<-sleep> +argument to change the interval). The log is cleared after each +write operation. + +The only acceptable value is B. Provide either this argument +or the B<-set> argument, or omit both to write out the B log by +default. + +=item B<-file> I + +Specifies the pathname of the file to which to write the trace +log's contents. It can be in AFS or on the local disk. Partial +pathnames are interpreted relative to the current working +directory. If this argument is omitted, the trace log appears +on the standard output stream. + +=item B<-sleep> I + +Sets the number of seconds between writes of the trace log's +contents when it is dumped continuously. Provide the B<-follow> +argument along with this one. If this argument is omitted, the +default interval is ten seconds. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output begins with a header specifying the date and time at which +the write operation began. If the B<-follow> argument is not included, +the header also reports the number of logs being dumped; it is always +1, since there is only the B trace log. The format of the header is +as follows: + + AFS Trace Dump - + Date: starting_timestamp + Found 1 logs. + Contents of log cmfx: + +Each subsequent message describes a Cache Manager operation in the +following format: + +time I, pid I:I + +where + +=over + +=item B + +Specifies the time at which the Cache Manager performed the +operation, as the number of seconds since the dump began + +=item B + +Specifies the process ID of the process or thread associated +with the message + +=item B + +Is the message itself. They are generally meaningful only to +someone familiar with the AFS source code. + +=back + +In addition, every 1024 seconds the C command interpreter writes +a message that records the current clock time, in the following +format: + +time I, pid I: Current time: I + +where + +=over + +=item B + +Is the number of seconds from the start of trace logging + +=item B + +Is the process ID number + +=item B + +Is the machine's clock time, represent in the standard UNIX +time format as the number of seconds since midnight on January +1, 1970. + +=back + +Use this message to determine the actual clock time associated with +each log message. Determine the actual time as follows: + +=over + +=item 1. + +Locate the message of interest. + +=item 2. + +Search backward through the trace file for the closest current +time message. + +=item 3. + +If the current time message's I is smaller than the log +message's I, subtract former from the latter. If the +current time message's I is larger than the log message's +I, add 1024 to the latter and subtract the former from the +result. + +=item 4. + +Add the resulting number to the current time message's I +to determine the log message's actual time. + +=back + +If any of the data in the kernel trace buffer has been overwritten +since tracing was activated, the following message appears at the +appropriate place in the output: + + Log wrapped; data missing. + +To reduce the likelihood of overwriting, use the C +command to increase the kernel buffer's size. To display the current +defined buffer size, use the C command with the B<-long> +argument. + +The following message at the end of the log dump indicates that it is +completed: + + AFS Trace Dump - Completed + +=head1 EXAMPLES + +The following command dumps the log associated with the cm event set +to the standard output stream. + + fstrace dump -set cm + AFS Trace Dump - + Date: Tue Apr 7 10:54:57 1998 + Found 1 logs. + time 32.965783, pid 0: Tue Apr 7 10:45:52 1998 + time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20 + time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0) + time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0) + time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0) + . + . + . + time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \ + fid (756 4fb7e:588d240.2ff978a8.6) + time 71.440569, pid 33658: Returning code 2 from 19 + time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2) + time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0) + AFS Trace Dump - Completed + +The following command dumps the trace log associated with the B event +set on the local machine to the file B, using the +default interval of 10 seconds between successive dumps: + + fstrace dump -follow cmfx -file cmfx.dump.file.1 + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +This command produces output only if the B event set is active. To +display or set the event set's state, use the C or C command respectively. + +To make the output from this command maximally readable, the message +catalog file called B must reside in the local +B directory. If necessary, copy the file to that +directory from the AFS Binary Distribution before activating tracing. + +When the B event set is active, a defined amount of kernel memory (by +default, 60 KB) is allocated for the B trace log. As described on +the introductory L reference page, when the buffer is full, +messages are overwritten in a circular fashion (new messages overwrite +the oldest ones). To allocate more kernel memory for the log, use the +C command; to display the log buffer's current size, use +the C command with the B<-long> argument. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_help.pod b/doc/man-pages/pod/fstrace_help.pod new file mode 100644 index 0000000000..cb1477f757 --- /dev/null +++ b/doc/man-pages/pod/fstrace_help.pod @@ -0,0 +1,94 @@ +=head1 NAME + +fstrace help - Displays the syntax of specified C commands or lists functional +descriptions of all C commands + +=head1 SYNOPSIS + +fstrace help [B<-topic> I [I ...]] [B<-help>] + +fstrace h [B<-t> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays the complete online help entry +(short description and syntax statement) for each command operation +code specified by the B<-topic> argument. If the B<-topic> argument is +omitted, the output includes the first line (name and short +description) of the online help entry for every C command. + +To list every C command whose name or short description includes +a specified keyword, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I [I ...] + +Indicates each command for which to display the complete online +help entry. Omit the C part of the command name, +providing only the operation code (for example, specify C, +not C). If this argument is omitted, the output +briefly describes every C command. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The online help entry for each C command consists of two or +three lines: + +=over + +=item * + +The first line names the command and briefly describes its +function. + +=item * + +The second line lists aliases for the command, if any. + +=item * + +The final line, which begins with the string C, lists the +command's options in the prescribed order. Online help entries use +the same symbols (for example, brackets) as the reference pages in +this document. + +=back + +=head1 EXAMPLES + +The following command displays the online help entry for the C command: + + fstrace help -topic setset + fstrace setset: set state of event sets + Usage: fstrace setset [-set +] [-active] [-inactive] + [-dormant] [-help] + +=head1 PRIVILEGE REQUIRED + +None + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_lslog.pod b/doc/man-pages/pod/fstrace_lslog.pod new file mode 100644 index 0000000000..07053f87d0 --- /dev/null +++ b/doc/man-pages/pod/fstrace_lslog.pod @@ -0,0 +1,109 @@ +=head1 NAME + +fstrace lslog - Displays information about a log + +=head1 SYNOPSIS + +fstrace lslog [B<-set> I [I ...]] [B<-log> I] [B<-long>] [B<-help>] + +fstrace lsl [B<-s> I [I ...]] [B<-log> I] [B<-lon>] [B<-h>] + +=head1 DESCRIPTION + +The C command reports whether the B log is available +for use. If the B<-long> argument is included, the output reports the +log's defined size, and whether that amount of space is currently +allocated in kernel memory or not. + +To change the B trace log's size, use the C command. +To display or set whether space is allocated for it in kernel memory, +use the C or C command to display or set the +state of the corresponding B event set, respectively. + +=head1 OPTIONS + +=over 4 + +=item B<-set> I [I ...] + +Names the event set for which to display information about the +corresponding trace log. The only acceptable value is B (for +which the associated trace log is B). Provide either this +argument or the B<-log> argument, or omit both to display +information about the B log by default. + +=item B<-log> I + +Names the trace log about which to report. The only acceptable +value is B. Provide either this argument or the B<-set> +argument, or omit both to report on the B log by default. + +=item B<-long> + +Reports the defined size of the log in kilobyte units and +whether that amount of space is currently allocated in kernel +memory. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +By default, the C command displays only the name of the +available log, B, in the following format: + + Available logs: + cmfx + +When the B<-long> flag is included, the output also reports the defined +size of the log in kilobytes, and whether or not that amount of space +is currently allocated in kernel memory, in the following format: + + Available logs: + cmfx : log_size kbytes (allocated | unallocated) + +The C state indicates that the indicated number of kilobytes +is reserved for the B trace log in kernel memory. The B event +set's state is either active or inactive, as reported by the C command, and set by the C command's B<-active> or +B<-inactive> flags respectively. + +The C state indicates that no kernel memory is currently +reserved for the B trace log. The B event set's state is dormant, +as reported by the C command and set by the C +command's B<-dormant> flag. If the event set's state is later changed to +active or inactive, the number of kilobytes indicated as I are +again allocated in kernel memory. + +=head1 EXAMPLES + +The following example uses the -long flag to display information about +the B log: + + fstrace lslog -log cmfx -long + Available logs: + cmfx : 60 kbytes (allocated) + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_lsset.pod b/doc/man-pages/pod/fstrace_lsset.pod new file mode 100644 index 0000000000..18dc096bc6 --- /dev/null +++ b/doc/man-pages/pod/fstrace_lsset.pod @@ -0,0 +1,90 @@ +=head1 NAME + +fstrace lsset - Reports the status of an event set + +=head1 SYNOPSIS + +fstrace lsset [B<-set> I [I ...]] [B<-help>] + +fstrace lss [B<-s> I [I ...]] [B<-h>] + +=head1 DESCRIPTION + +The C command displays a list of the available event sets +and reports their current status (active, inactive, or dormant). + +To change an event set's status, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-set> I [I ...] + +Names the event set for which to display the status. The only +acceptable value is B, which is also the default if this +argument is omitted. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output lists the available event sets and the status of each, in +the following format: + + Available sets: + cm {active | inactive | dormant} + +where + +=over + +=item B + +Indicates that tracing is enabled for the event set, and kernel +memory allocated for the corresponding trace log. + +=item B + +Indicates that tracing is temporarily disabled for the event +set, but kernel memory still allocated for the corresponding +trace log. + +=item B + +Indicates that tracing is disabled for the event set, and no +kernel memory allocated for the corresponding trace log. + +=back + +=head1 EXAMPLES + +The following example displays the available event set and its status: + + fstrace lsset + Available sets: + cm active + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_setlog.pod b/doc/man-pages/pod/fstrace_setlog.pod new file mode 100644 index 0000000000..a44d94eacf --- /dev/null +++ b/doc/man-pages/pod/fstrace_setlog.pod @@ -0,0 +1,74 @@ +=head1 NAME + +fstrace setlog - Sets the size of a trace log + +=head1 SYNOPSIS + +fstrace setlog [B<-log> I [I ...]] B<-buffersize> I<1-kilobyte_units> [B<-help>] + +fstrace setl [B<-l> I [I ...]] B<-b> I<1-kilobyte_units> [B<-h>] + +fstrace sl [B<-l> I [I ...]] B<-b> I<1-kilobyte_units> [B<-h>] + +=head1 DESCRIPTION + +The C command defines the number of kilobytes of kernel +memory allocated for the B trace log. If kernel memory is currently +allocated, the command clears the current log and creates a new log +buffer of the specified size. + +To display the current defined size of the log buffer, issue the +C command with the B<-long> argument. To control whether the +indicated amount of space is actually allocated, use the C command to set the status of the cm event set; to display the +event set's status, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-log> I [I ...] + +Names trace log for which to set the size. The only acceptable +value is B, which is also the default if this argument is +omitted. + +=item B<-buffersize> I<1-kilobyte_units> + +Specifies the number of 1-kilobyte blocks of kernel memory to +allocate for the trace log. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following command allocated 80 KB of kernel memory for the B +trace log: + + fstrace setlog -log cmfx -buffersize 80 + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/fstrace_setset.pod b/doc/man-pages/pod/fstrace_setset.pod new file mode 100644 index 0000000000..db392cf389 --- /dev/null +++ b/doc/man-pages/pod/fstrace_setset.pod @@ -0,0 +1,79 @@ +=head1 NAME + +fstrace setset - Sets the status of an event set + +=head1 SYNOPSIS + +fstrace setset [B<-set> I [I ...]] [B<-active>] [B<-inactive>] [B<-dormant>] [B<-help>] + + +fs set [B<-s> I [I ...]] [B<-a>] [B<-i>] [B<-d>] [B<-h>] + +=head1 DESCRIPTION + +The C command sets the status of the B kernel event set +on the local machine, which determines whether trace messages are +recorded in the log buffer in kernel memory. + +=head1 OPTIONS + +=over 4 + +=item B<-set> I [I ...] + +Names the event set for which to set the status. The only +acceptable value is B, which is also the default if this argument +is omitted. + +=item B<-active> + +Enables tracing for the event set and allocates kernel memory +for the associated trace log buffer. Provide one of this flag, +the B<-inactive> flag, or the B<-dormant> flag. + +=item B<-inactive> + +Temporarily disables tracing for the event set, but does not +change the allocation of kernel memory for the associated trace +log buffer. Provide one of this flag, the B<-active> flag, or the +B<-dormant> flag. + +=item B<-dormant> + +Disables tracing for the event set and frees the kernel memory +previously allocated for the associated trace log buffer. +Provide one of this flag, the B<-active> flag, or the B<-inactive> +flag. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example sets the B event set's status to B: + + fstrace setset -set cm -inactive + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/kadb_check.pod b/doc/man-pages/pod/kadb_check.pod new file mode 100644 index 0000000000..f4c9b8f797 --- /dev/null +++ b/doc/man-pages/pod/kadb_check.pod @@ -0,0 +1,102 @@ +=head1 NAME + +kadb_check - Checks the integrity of the Authentication Database + +=head1 SYNOPSIS + +kadb_check B<-database> I [B<-uheader>] [B<-kheader>] [B<-entries>] +[B<-verbose>] [B<-rebuild> I] [B<-help>] + +kadb_check B<-d> I [B<-u>] [B<-k>] [B<-e>] [B<-v>] [B<-r> I] [B<-h>] + +=head1 DESCRIPTION + +The C command checks the integrity of the Protection +Database, reporting any errors or corruption it finds. If there are +problems, do not issue any C commands until the database is +repaired. + +=head1 OPTIONS + +=over 4 + +=item B<-database> I + +Names the Authentication Database (copy of the B +file) to check. If the current working directory is not the +location of the file, provide a pathname, either full or +relative to the current working directory. + +=item B<-uheader> + +Displays information which Ubik maintains in the database's +header. + +=item B<-kheader> + +Displays information which the Authentication Server maintains +in the database's header. + +=item B<-entries> + +Outputs every entry in the database, providing information +similar to that returned by the C command. + +=item B<-verbose> + +Reports additional information about the database, including +the number of free (allocated but unused) entries in the +database. + +=item B<-rebuild> I + +Names the file in which to record a list of C commands which, +if issued in the command shell, recreate the current state of +the database being verified. Partial pathnames are interpreted +relative to the current working directory. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +If there are errors in the database, the output always reports them on +the standard error stream. If any options other than B<-database> or +B<-help> are provided, the output written to the standard output stream +includes additional information as described for each option in the +preceding L section of this reference page. The output is +intended for debugging purposes and is meaningful to someone familiar +with the internal structure of the Authentication Database. + +=head1 PRIVILEGE REQUIRED + +The issuer must be logged in as the local superuser B. + +=head1 CAVEATS + +The results can be unpredictable if the Authentication Server makes +changes to the Authentication Database while this command is running. +Use the C command to shutdown the local B process +before running this command, or before creating a second copy of the +B file (with a different name) on which to run the command. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +kaserver.DB0 and kaserver.DBSYS1, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/kas.pod b/doc/man-pages/pod/kas.pod new file mode 100644 index 0000000000..bddd681771 --- /dev/null +++ b/doc/man-pages/pod/kas.pod @@ -0,0 +1,214 @@ +=head1 NAME + +kas - Introduction to the C command suite + +=head1 DESCRIPTION + +The commands in the C command suite are the administrative interface +to the Authentication Server, which runs on each database server +machine in a cell, maintains the Authentication Database, and provides +the authentication tickets that client applications must present to +AFS servers in order to obtain access to AFS data and other services. + +There are several categories of commands in the C command suite: + +=over + +=item * + +Commands to create, modify, examine and delete entries in the +Authentication Database, including passwords: C, C, C, C, C, C, C, and C + +=item * + +Commands to create, delete, and examine tokens and server tickets: +C, C, C, and C + +=item * + +A command to enter interactive mode: C + +=item * + +A command to trace Authentication Server operations: C + +=item * + +Commands to obtain help: C and C + +=back + +Because of the sensitivity of information in the Authentication +Database, the Authentication Server authenticates issuers of C +commands directly, rather than accepting the standard token generated +by the Ticket Granting Service. Any C command that requires +administrative privilege prompts the issuer for a password. The +resulting ticket is valid for six hours unless the maximum ticket +lifetime for the issuer or the Authentication Server's Ticket Granting +Service is shorter. + +To avoid having to provide a password repeatedly when issuing a +sequence of C commands, enter I by issuing the C command, typing C without any operation code, or typing +C followed by a user and cell name, separated by an at-sign (@; an +example is C). After prompting once for a +password, the Authentication Server accepts the resulting token for +every command issued during the interactive session. See the reference +page for the C command for a discussion of when to use +each method for entering interactive mode and of the effects of +entering a session. + +The Authentication Server maintains two databases on the local disk of +the machine where it runs: + +=over + +=item * + +The Authentication Database (B) stores the +information used to provide AFS authentication services to users +and servers, including the password scrambled as an encryption +key. The reference page for the C command describes the +information in a database entry. + +=item * + +An auxiliary file (B by default) that tracks +how often the user has provided an incorrect password to the local +Authentication Server. The reference page for the C +command describes how the Authentication Server uses this file to +enforce the limit on consecutive authentication failures. To +designate an alternate directory for the file, use the C +command's B<-localfiles> argument. + +=back + +=head1 OPTIONS + +The following arguments and flags are available on many commands in +the C suite. (Some of them are unavailable on commands entered in +interactive mode, because the information they specify is established +when entering interactive mode and cannot be changed except by leaving +interactive mode.) The reference page for each command also lists +them, but they are described here in greater detail. + +=over 4 + +=item B<-admin_username> + +Specifies the user identity under which to authenticate with +the Authentication Server for execution of the command. If this +argument is omitted, the C command interpreter requests +authentication for the identity under which the issuer is +logged onto the local machine. Do not combine this argument +with the B<-noauth> flag. + +=item B<-cell> I + +Names the cell in which to run the command. It is acceptable to +abbreviate the cell name to the shortest form that +distinguishes it from the other entries in the +B file on the local machine. If the +B<-cell> argument is omitted, the command interpreter determines +the name of the local cell by reading the following in order: + +=over + +=item 1. + +The value of the AFSCELL environment variable + +=item 2. + +The local B file + +=back + +The B<-cell> argument is not available on commands issued in +interactive mode. The cell defined when the C command +interpreter enters interactive mode applies to all commands +issued during the interactive session. + +=item B<-help> + +Prints a command's online help message on the standard output +stream. Do not combine this flag with any of the command's +other options; when it is provided, the command interpreter +ignores all other options, and only prints the help message. + +=item B<-noauth> + +Establishes an unauthenticated connection to the Authentication +Server, in which the Authentication Server treats the issuer as +the unprivileged user B. It is useful only when +authorization checking is disabled on the server machine +(during the installation of a server machine or when the C command has been used during other unusual +circumstances). In normal circumstances, the Authentication +Server allows only privileged users to issue most C commands, +and refuses to perform such an action even if the B<-noauth> flag +is provided. Do not combine this flag with the B<-admin_username> +and B<-password_for_admin> arguments. + +=item B<-password_for_admin> + +Specifies the password of the command's issuer. It is best to +omit this argument, which echoes the password visibly in the +command shell, instead enter the password at the prompt. Do not +combine this argument with the B<-noauth> flag. + +=item B<-servers> + +Establishes a connection with the Authentication Server running +on each specified database server machine, instead of on each +machine listed in the local B file. In +either case, the C command interpreter then chooses one of +the machines at random to contact for execution of each +subsequent command. The issuer can abbreviate the machine name +to the shortest form that allows the local name service to +identify it uniquely. + +=back + +=head1 PRIVILEGE REQUIRED + +To issue most C commands, the issuer must have the C flag set in +his or her Authentication Database entry (use the C +command to turn the flag on). + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L and L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/kas_apropos.pod b/doc/man-pages/pod/kas_apropos.pod new file mode 100644 index 0000000000..f3406a6102 --- /dev/null +++ b/doc/man-pages/pod/kas_apropos.pod @@ -0,0 +1,69 @@ +=head1 NAME + +kas apropos - Displays each help entry containing a keyword string + +=head1 SYNOPSIS + +kas apropos B<-topic> I [B<-help>] + +kas a B<-t> I [B<-h>] + +=head1 DESCRIPTION + +The C command displays the first line of the online help +entry for any C command that has the string specified by the B<-topic> +argument in its name or short description. + +To display the syntax for a command, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-topic> I + +Specifies the keyword string to match, in lowercase letters +only. If the string is more than a single word, surround it +with double quotes ("") or other delimiters. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The first line of a command's online help entry names it and briefly +describes its function. This command displays the first line for any +C command where the string specified with the B<-topic> argument is +part of the command name or first line. + +=head1 EXAMPLES + +The following command lists all C commands that include the word B +in their names or short descriptions: + + kas apropos key + setkey: set a user's key + stringtokey: convert a string to a key + +=head1 PRIVILEGE REQUIRED + +None, and no password is required. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/kas_create.pod b/doc/man-pages/pod/kas_create.pod new file mode 100644 index 0000000000..1da1b5b9f9 --- /dev/null +++ b/doc/man-pages/pod/kas_create.pod @@ -0,0 +1,125 @@ +=head1 NAME + +kas create - Creates an entry in the Authentication Database + +=head1 SYNOPSIS + +kas create S I> +S<[B<-initial_password> I]> +S<[B<-admin_username> I]> +S<[B<-password_for_admin> I]> +S<[B<-cell> I]> +S<[B<-servers> I ...]> +[B<-noauth>] [B<-help>] + +kas c B<-na> I S<[B<-i> I]> +S<[B<-a> I]> +S<[B<-p> I]> S<[B<-c> I]> +S<[B<-s> I ...]> [B<-no>] [B<-h>] + +=head1 DESCRIPTION + +The C command creates an entry in the Authentication Database +for the user named by the B<-name> argument. + +To avoid having the account's initial password echo visibly at the +shell prompt, omit the B<-initial_password> argument; the command +interpreter prompts for the password and does not echo it visibly. +Whether or not B<-initial_password> is omitted, the Authentication Server +converts the password into a form suitable for use as an encryption +key, and records it in the entry's key field. + +To alter settings in an Authentication Database entry, use the C command. To examine an entry, use the C command. +To list every entry in the database, use the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-name> I + +Names the new Authentication Database entry. Because it is the +name under which the user logs in, it must obey the +restrictions that many operating systems impose on user names +(usually, to contain no more than eight lowercase letters). + +=item B<-initial_password> I + +Sets the user's password; provide a character string that can +include uppercase and lowercase letters, numerals and +punctuation. The Authentication Server scrambles the string +into an octal string suitable for use as an encryption key +before placing it in the entry's key field. If this argument is +omitted, the command interpreter prompts for the string and +does not echo it visibly. + +=item B<-admin_username> I + +Specifies the user identity under which to authenticate with +the Authentication Server for execution of the command. For +more details, see the introductory L reference page. + +=item B<-password_for_admin> I + +Specifies the password of the command's issuer. If it is +omitted (as recommended), the C command interpreter prompts +for it and does not echo it visibly. For more details, see the +introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. For more details, +see the introductory L reference page. + +=item B<-servers> I ... + +Names each machine running an Authentication Server with which +to establish a connection. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example shows the prompts that appear when an +administrator logged in as B creates an Authentication Database +entry for the user B, and does not include either the +B<-initial_password> or B<-password_for_admin arguments>. + + kas create smith + Password for admin: + initial_password: + Verifying, please re-enter initial_password: + +=head1 PRIVILEGE REQUIRED + +The issuer must have the C flag set on his or her Authentication +Database entry. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L, +L, +L + +=cut diff --git a/doc/man-pages/pod/kas_delete.pod b/doc/man-pages/pod/kas_delete.pod new file mode 100644 index 0000000000..05195e4655 --- /dev/null +++ b/doc/man-pages/pod/kas_delete.pod @@ -0,0 +1,102 @@ +=head1 NAME + +kas delete - Deletes an entry from the Authentication Database + +=head1 SYNOPSIS + +kas delete B<-name> I +S<[B<-admin_username> I]> +S<[B<-password_for_admin> I]> S<[B<-cell> I]> +S<[B<-servers> I ...]> +[B<-noauth>] [B<-help>] + +kas d B<-na> I [B<-a> I] +[B<-p> I] [B<-c> I] +[B<-s> I ...] [B<-no>] [B<-h>] + +kas rm B<-na> I [B<-a> I] +[B<-p> I] [B<-c> I] +[B<-s> I ...] [B<-no>] [B<-h>] + +=head1 DESCRIPTION + +The C command removes from the Authentication Database the +user entry named by the B<-name> argument. The indicated user becomes +unable to log in, or the indicated server becomes unreachable (because +the Authentication Server's Ticket Granting Service module no longer +has a key with which to seal tickets for the server). + +=head1 OPTIONS + +=over 4 + +=item B<-name> I + +Names the Authentication Database entry to delete. + +=item B<-admin_username> I + +Specifies the user identity under which to authenticate with +the Authentication Server for execution of the command. For +more details, see the introductory L reference page. + +=item B<-password_for_admin> I + +Specifies the password of the command's issuer. If it is +omitted (as recommended), the C command interpreter prompts +for it and does not echo it visibly. For more details, see the +introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. For more details, +see the introductory L reference page. + +=item B<-servers> I ... + +Names each machine running an Authentication Server with which +to establish a connection. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 EXAMPLES + +The following example shows the administrative user B entering +interactive mode to delete three accounts. + + kas + Password for admin: + ka> delete smith + ka> delete pat + ka> delete terry + +=head1 PRIVILEGE REQUIRED + +The issuer must have the C flag set on his or her Authentication +Database entry. + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Converted from html to pod by Alf Wachsmann , 2003, +and Elizabeth Cassell , 2004, +Stanford Linear Accelerator Center, a department of Stanford University. + +=head1 SEE ALSO + +L, +L + +=cut diff --git a/doc/man-pages/pod/kas_examine.pod b/doc/man-pages/pod/kas_examine.pod new file mode 100644 index 0000000000..254256fc80 --- /dev/null +++ b/doc/man-pages/pod/kas_examine.pod @@ -0,0 +1,308 @@ +=head1 NAME + +kas examine - Displays information from an Authentication Database entry + +=head1 SYNOPSIS + +kas examine B<-name> I [B<-showkey>] +[B<-admin_username> I] +[B<-password_for_admin> I] [B<-cell> I] +[B<-servers> I ...] +[B<-noauth>] [B<-help>] + +kas e B<-na> I [B<-sh>] +[B<-a> I] +[B<-p> I] [B<-c> I] +[B<-se> I ...] [B<-no>] [B<-h>] + +=head1 DESCRIPTION + +The C command formats and displays information from the +Authentication Database entry of the user named by the B<-name> argument. + +To alter the settings displayed with this command, issue the C command. + +=head1 OPTIONS + +=over 4 + +=item B<-name> I + +Names the Authentication Database entry from which to display +information. + +=item B<-showkey> + +Displays the octal digits that constitute the key. The issuer +must have the C flag on his or her Authentication Database +entry. + +=item B<-admin_username> I + +Specifies the user identity under which to authenticate with +the Authentication Server for execution of the command. For +more details, see the introductory L reference page. + +=item B<-password_for_admin> I + +Specifies the password of the command's issuer. If it is +omitted (as recommended), the C command interpreter prompts +for it and does not echo it visibly. For more details, see the +introductory L reference page. + +=item B<-cell> I + +Names the cell in which to run the command. For more details, +see the introductory L reference page. + +=item B<-servers> I ... + +Names each machine running an Authentication Server with which +to establish a connection. For more details, see the +introductory L reference page. + +=item B<-noauth> + +Assigns the unprivileged identity B to the issuer. For +more details, see the introductory L reference page. + +=item B<-help> + +Prints the online help for this command. All other valid +options are ignored. + +=back + +=head1 OUTPUT + +The output includes: + +=over + +=item * + +The entry name, following the string C. + +=item * + +One or more status flags in parentheses; they appear only if an +administrator has used the C command to change them +from their default values. A plus sign (+) separates the flags if +there is more than one. The nondefault values that can appear, and +their meanings, are as follows: + +=over + +=item B + +Enables the user to issue privileged C commands +(default is C) + +=item B + +Prevents the user from obtaining tickets from the +Authentication Server's Ticket Granting Service (default +is C) + +=item B + +Prevents the Ticket Granting Service from using the +entry's key field as an encryption key (default is C) + +=item B + +Prevents the user from changing his or her password +(default is C) + +=back + +=item * + +The key version number, in parentheses, following the word C, +then one of the following. + +=over + +=item * + +A checksum equivalent of the key, following the string C, if the B<-showkey> flag is not included. The checksum is a +decimal number derived by encrypting a constant with the key. +In the case of the B entry, this number must match the +checksum with the corresponding key version number in the +output of the C command; if not, follow the +instructions in the IBM AFS Administration Guide for creating +a new server encryption key. + +=item * + +The actual key, following a colon, if the B<-showkey> flag is +included. The key consists of eight octal numbers, each +represented as a backslash followed by three decimal digits. + +=back + +=item * + +The date the user last changed his or her own password, following +the string C (which stands for "last change of password"). + +=item * + +The string C indicates that the +associated password never expires; the string C +is followed by the password's expiration date. After the indicated +date, the user cannot authenticate, but has 30 days after it in +which to use the C or C command to set a new +password. After 30 days, only an administrator (one whose account +is marked with the C flag) can change the password by using +the C command. To set the password expiration date, +use the C command's B<-pwexpires> argument. + +=item * + +The number of times the user can fail to provide the correct +password before the account locks, followed by the string +C, or the +string C to indicate that there is no limit. To set the limit, +use the C command's B<-attempts> argument. To unlock a +locked account, use the C command. The L +reference page discusses how the implementation of the lockout +feature interacts with this setting. + +=item * + +The number of minutes for which the Authentication Server refuses +the user's login attempts after the limit on consecutive +unsuccessful authentication attempts is exceeded, following the +string C. Use the C command's +B<-locktime> argument to set the lockout time. This line appears only +if a limit on the number of unsuccessful authentication attempts +has been set with the the C command's B<-attempts> +argument. + +=item * + +An indication of whether the Authentication Server is currently +refusing the user's login attempts. The string C +indicates that authentication can succeed, whereas the string C I