[hcoop/debian/openafs.git] / doc / man-pages / pod1 / fs_cscpolicy.pod

=head1 NAME

fs_cscpolicy - Change client side caching policy for AFS shares [Windows only]

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<fs cscpolicy> S<<< [B<-share> I<sharename> [B<-manual>|B<-programs>|B<-documents>|B<-disable>] ] >>>

=for html
</div>

=head1 DESCRIPTION

The fs cscpolicy command sets the client side caching policy for a
particular AFS share, or displays a list of policies.

This command can change the policy of only one share at a time.

Only one of the policy options B<-manual>, B<-programs>, B<-documents>, or
B<-disable>, may be selected.  The default policy is B<-manual>.

After changing the policy for a share, you must close all applications
that accessed files on this share, or restart AFS Client, for the change
to take effect.

=head1 CAUTIONS

This command is only available on Windows.

Use of this functionality is not recommended.  Windows Offline Folders do
not work well with AFS since the AFS server is always present.  When this
functionality was contributed and incorporated, it was believed to be safe
for the AFS cache manager to return BADNETPATH errors when a single file
server or volume was inaccessible.  It is now known that returning such
errors causes the Microsoft SMB redirector to drop the connection to the
AFS server resulting in serious side effects.

This functionality is specific to use with the Microsoft SMB redirector.
Client Side Caching (Offline Folders) is built into that driver and will
not be present in the native AFS redirector, so this functionality will be
removed at a future date.

=head1 OPTIONS

=over 4

=item B<-share> I<sharename>

The name of the share whose policy is to be changed.  (If omitted, no
share policy is changed.)

=item B<-manual>

Specifies manual caching of documents.

=item B<-programs>

Specifies automatic caching of programs and documents.

=item B<-documents>

Specifies automatic caching of documents.

=item B<-disable>

Disables caching.

=back

=head1 OUTPUT

When changing the policy of a share, the output is:

   CSC policy on share "share" changed to "policy".
   Close all applications that accessed files on this share or restart AFS Client for the change to take effect.

When displaying policies, the output is:

   policyname = policy

=head1 EXAMPLES

The following command disables all caching on the share "AFS1":

   % fs cscpolicy -share AFS1 -disable

The following command displays all policies currently in effect:

   % fs cscpolicy

=head1 PRIVILEGE REQUIRED

The issuer must be have AFS Client Administrator access, either to display
or to set policies.

In addition, to change policies, the issuer must be a Windows
Administrator, since policy information is stored in a protected area of
the Windows Registry.

=head1 COPYRIGHT

This document was written by Mike Robinson, and is released under the IBM
Public License Version 1.0.  Jeffrey Altman made several corrections,
clarifications, and additions.
Commit	Line	Data
805e021f CE	1	=head1 NAME
	2
	3	fs_cscpolicy - Change client side caching policy for AFS shares [Windows only]
	4
	5	=head1 SYNOPSIS
	6
	7	=for html
	8	<div class="synopsis">
	9
	10	B<fs cscpolicy> S<<< [B<-share> I<sharename> [B<-manual>\|B<-programs>\|B<-documents>\|B<-disable>] ] >>>
	11
	12	=for html
	13	</div>
	14
	15	=head1 DESCRIPTION
	16
	17	The fs cscpolicy command sets the client side caching policy for a
	18	particular AFS share, or displays a list of policies.
	19
	20	This command can change the policy of only one share at a time.
	21
	22	Only one of the policy options B<-manual>, B<-programs>, B<-documents>, or
	23	B<-disable>, may be selected. The default policy is B<-manual>.
	24
	25	After changing the policy for a share, you must close all applications
	26	that accessed files on this share, or restart AFS Client, for the change
	27	to take effect.
	28
	29	=head1 CAUTIONS
	30
	31	This command is only available on Windows.
	32
	33	Use of this functionality is not recommended. Windows Offline Folders do
	34	not work well with AFS since the AFS server is always present. When this
	35	functionality was contributed and incorporated, it was believed to be safe
	36	for the AFS cache manager to return BADNETPATH errors when a single file
	37	server or volume was inaccessible. It is now known that returning such
	38	errors causes the Microsoft SMB redirector to drop the connection to the
	39	AFS server resulting in serious side effects.
	40
	41	This functionality is specific to use with the Microsoft SMB redirector.
	42	Client Side Caching (Offline Folders) is built into that driver and will
	43	not be present in the native AFS redirector, so this functionality will be
	44	removed at a future date.
	45
	46	=head1 OPTIONS
	47
	48	=over 4
	49
	50	=item B<-share> I<sharename>
	51
	52	The name of the share whose policy is to be changed. (If omitted, no
	53	share policy is changed.)
	54
	55	=item B<-manual>
	56
	57	Specifies manual caching of documents.
	58
	59	=item B<-programs>
	60
	61	Specifies automatic caching of programs and documents.
	62
	63	=item B<-documents>
	64
65	Specifies automatic caching of documents.
66
67	=item B<-disable>
68
69	Disables caching.
70
71	=back
72
73	=head1 OUTPUT
74
75	When changing the policy of a share, the output is:
76
77	CSC policy on share "share" changed to "policy".
78	Close all applications that accessed files on this share or restart AFS Client for the change to take effect.
79
80	When displaying policies, the output is:
81
82	policyname = policy
83
84	=head1 EXAMPLES
85
86	The following command disables all caching on the share "AFS1":
87
88	% fs cscpolicy -share AFS1 -disable
89
90	The following command displays all policies currently in effect:
91
92	% fs cscpolicy
93
94	=head1 PRIVILEGE REQUIRED
95
96	The issuer must be have AFS Client Administrator access, either to display
97	or to set policies.
98
99	In addition, to change policies, the issuer must be a Windows
100	Administrator, since policy information is stored in a protected area of
101	the Windows Registry.
102
103	=head1 COPYRIGHT
104
105	This document was written by Mike Robinson, and is released under the IBM
106	Public License Version 1.0. Jeffrey Altman made several corrections,
107	clarifications, and additions.