Fix broken directory links
[openafs-wiki.git] / reguser / OpenAFSVolumeBasics.mdwn
1 = About volumes =
2
3 AFS uses a service to lookup IP addresses of file servers using the volume name or the volume number. The volume location database is in charge of looking up the file server IP addresses. The command 'vos listvldb' acts like the 'dig' or 'nslookup' command in DNS.
4
5
6 Mount points are actually link files that point to the original location of a file.
7
8
9 If the cache manager starts with read only data it sticks with read only data. If the cache manager starts with read write data it sticks with read write data.
10
11 = How does the client find volumes? =
12
13 Show how the client finds volumes by walking each path component
14 using fs examine, fs lsmount, and vos listvldb.
15
16 Example: To show the volumes and locations of those volumes to reach
17 <code>/afs/acme.com/user/lily</code>
18
19 Beginning with showing volume id of root.cell
20
21     $ fs examine /afs/acme.com
22     File /afs/acme.com (536870915.1.1) contained in volume 536870915
23     Volume status for vid = 536870915 named root.cell
24     Current disk quota is 5000
25     Current blocks used are 4
26     The partition has 945244 blocks available out of 946892
27
28 Finding the location of root.cell: Use the $ vos listvldb -name <name-or-number> command
29
30     $ vos listvldb -name root.cell
31     root.cell
32     RWrite: 536870915
33     number of sites -> 1
34     server afs02.classroom.sinenomine.net partition /vicepa RW Site
35
36 Next go down the path to /afs/acme.com/user to find the volume name/number
37 using the fs examine /afs/acme.com/user command
38
39     $fs examine /afs/acme.com/user
40     File /afs/acme.com/user (536870921.1.1) contained in volume 536870921
41     Volume status for vid = 536870921 named user
42     Current disk quota is 5000
43     Current blocks used are 4
44     The partition has 945244 blocks available out of 946892
45
46 To find the location of the volume for /afs/acme.com/user (name = user and
47 536870921 is the volume number) use vos listvldb -name <name-or-number> command
48
49     $ vos listvldb -name user
50     user
51       RWrite: 536870921
52       number of sites -> 1
53       server afs02.classroom.sinenomine.net partition /vicepa RW Site
54
55 For the last path for this example use the fs examine /afs/acme.com/user/lily
56 command to find the volume name/number
57
58     $ fs examine /afs/acme.com/user/lily
59     File /afs/acme.com/user/lily (536870927.1.1) contained in volume 536870927
60     Volume status for vid = 536870927 named user.lily
61     Current disk quota is 5000
62     Current blocks used are 2
63     The partition has 945244 blocks available out of 946892
64
65 To find the location of user.lily volume use the following command:
66
67     $ vos listvldb -name user.lily
68     user.lily
69       RWrite: 536870927
70       number of sites -> 1
71         server afs02.classroom.sinenomine.net partition /vicepa RW Site
72
73
74 Summary:
75
76     /afs          ---> root.afs generated by -dynroot
77       /acme.com   ---> root.cell on afs02 /vicepa
78         /user     ---> user on afs02 /vicepa
79           /lily   ---> user.lily on afs02 /vicepa
80
81
82 Use the following command to show the mount points under /afs/acme.com/user/
83
84     $ fs lsmount /afs/acme.com/user/*
85     '/afs/acme.com/user/goose' is a mount point for volume '#user.goose'
86     '/afs/acme.com/user/lily' is a mount point for volume '#user.lily'
87
88
89
90
91 All files have a three part number called an FID, pronounced like 'kid', that the cache manager uses to find the location.
92
93 == Reading Data ==
94
95 Assume that the client knows the number for a file called "myfile". The number is 536870930.2.2. The client knows that "myfile" is located on the volume numbered 536870930 which is the first part of the FID. The volume is located at network address 10.0.10.21. That network address is really afs01, but the file is actually under /vicepa.
96
97 The client will send a "FetchData" request with the FID, 536870930.2.2, to the file server running on 10.0.10.21. The file server will take in that request, read it at /vicepa, and then return the data in the file. 
98
99 == Writing Data ==
100
101 Writing data is similar to the reading data process except the data flows the other way and the "FetchData" command becomes "StoreData".
102
103 == Cache Manager knows FID ==
104
105 1. The cache manager looks in the CellServDB to find the address(s) of the Volume Location Database server(s), VLDB.
106
107 2. The cache manager requests the IP addresses for the volume numbered 536870930.
108
109 3. The VLDB returns the location: 10.0.10.21
110
111 4. The cache manager requests the data from server 10.0.10.21
112
113 5. The file server process reads the file in /vicepa and sends the data to the cache manager.
114
115 6. The cache manager has the data and stores it in a local file. It then hands the data over to the operating system.
116
117 == Cache Manager learns FID using the Directory Number ==
118
119 In this case the cache manager has the FID for the directory where the file is stored, 536870930.1.1.
120
121 1. Cache manager checks CellServDB for the address(es) of the VLDB.
122
123 2. Cache manager sends a request to the VLDB for the IP address for volume 536870930.
124
125 3. VLDB says its on 10.0.10.21
126
127 4. Cache manager requests the data from 10.0.10.21
128
129 5. The file server process on 10.0.10.21 reads the file in /vicepa and returns the data to the cache manager. The data says that it contains my file at .2.2.
130
131 6. Cache manager now has the data and saves it to a local file in the cache.
132
133 = About volume quotas =
134
135 Default volume quotas are tiny, 5MB. Use the fs command to change the
136 quota (requires admin access rights).
137
138 == Viewing quotas ==
139
140 Use <code>fs listquota /afs/<cellname>/<path></code> to view volume quotas.
141
142 Example:
143
144     fs listquota /afs/acme.com/user/lily
145     Volume Name                    Quota       Used   %Used   Partition
146     user.lily                      20000       6146   31%          1% 
147
148 == Setting quotas ==
149
150 Use <code>fs setquota /afs/<cellname>/<path> -m <nmber kb block></code> to set volume quotas.
151
152 Example:
153
154     fs setquota /afs/<cellname>/<path> -m 20000
155
156 Go back and check that the setquota worked by using the fs listquota above.
157
158 = How to make new volumes =
159
160 Use vos create and fs mkmount to create new volumes. Use
161 the vos create -m option to set the initial quota.
162
163 First get a token.
164
165 Below is an example that sets the quota to 0 which will disable the quota:
166     vos create afs01 a project.mayhem -m 0
167     fs mkmount /afs/yoyodyne.com/mayhem project.mayhem
168
169 Then set the access rights:
170     fs sa /afs/yoyodyne.com/mayhem/ mayhem write
171
172 = How to remove volumes =
173
174 fs rmmount to remove mount points.
175
176 vos remove to delete the volume data. (With caution!)
177
178 1. First remove the mount points:
179
180     fs lsmount /afs/yoyodyne.com/mayhem
181     fs rmmount /afs/yoyodyne.com/mayhem
182     ls /afs/yoyodyne.com/
183
184 2. Now delete the data:
185     vos remove -id project.mayhem
186     vos listvol afs01
187
188 = How to move volumes =
189
190 Use vos move to move the volume to anther fileserver or partition.
191
192 1. Check the volumes on each partition on the fileserver. Then move a volume from partition a to partition b::
193
194     vos listvol afs01
195     vos move -id user -fromserver afs01 -frompartition a -toserver afs01 -topartition b
196     vos listvol afs01
197
198 2. The backup was removed, so create a new one:
199
200     vos backup project
201     vos listvol afs01
202
203 = How to dump volumes =
204
205 Use vos backup to make a snapshot, and then vos dump to dump an "archive" of
206 the volume.
207
208 '''Note''': the file name for this lab is 'project.mayhem'
209
210
211 1. Log in as admin and collect a token. Next create a backup volume:
212     kinit admin && aklog && tokens
213     vos backup -id project.mayhem
214     vos listvldb -name project.mayhem
215
216     
217 2. Then dump the whole volume:
218     vos dump -id project.mayhem -file /tmp/project.mayhem.dump
219     
220     file /tmp/project.mayhem.dump
221     
222 3. Now restore the the volume:
223     vos restore -server afs01 -partition b -name project.mayhem.2 -file /tmp/project.mayhem.dump
224     vos listvldb -name project.mayhem.2
225     fs mkmount /afs/yoyodyne.com/mayhem2 project.mayhem.2
226
227 4. Remove the old dump and create a new one:
228     rm /tmp/project.mayhem.dump
229     vos dump -id project.mayhem.backup -file /tmp/project.mayhem.dump
230     file /tmp/project.mayhem.dump
231
232 Sine Nomine Associates Nov 2017