4002bea26bf15c19800e65829aa546f0defa5589
[dragonfly.git] / share / man / man8 / swapcache.8
1 .\"
2 .\" swapcache - Cache clean filesystem data & meta-data on SSD-based swap
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .Dd February 7, 2010
13 .Dt SWAPCACHE 8
14 .Os
15 .Sh NAME
16 .Nm swapcache
17 .Nd a
18 mechanism which allows the system to use fast swap to cache filesystem
19 data and meta-data.
20 .Sh SYNOPSIS (defaults shown)
21 .Cd sysctl vm.swapcache.accrate=100000
22 .Cd sysctl vm.swapcache.maxfilesize=0
23 .Cd sysctl vm.swapcache.maxburst=2000000000
24 .Cd sysctl vm.swapcache.curburst=4000000000
25 .Cd sysctl vm.swapcache.minburst=10000000
26 .Cd sysctl vm.swapcache.read_enable=0
27 .Cd sysctl vm.swapcache.meta_enable=0
28 .Cd sysctl vm.swapcache.data_enable=0
29 .Cd sysctl vm.swapcache.use_chflags=1
30 .Cd sysctl vm.swapcache.maxlaunder=256
31 .Sh DESCRIPTION
32 .Nm
33 is a system capability which allows a solid state disk (SSD) in a swap
34 space configuration to be used to cache clean filesystem data and meta-data
35 in addition to its normal function of backing anonymous memory.
36 .Pp
37 Sysctls are used to manage operational parameters and can be adjusted at
38 any time.  Typically a large initial burst is desired after system boot,
39 controlled by the initial
40 .Cd vm.swapcache.curburst
41 parameter.
42 This parameter is reduced as data is written to swap by the swapcache
43 and increased at a rate specified by
44 .Cd vm.swapcache.accrate .
45 Once this parameter reaches zero write activity ceases until it has
46 recovered sufficiently for write activity to resume.
47 .Pp
48 .Cd vm.swapcache.meta_enable
49 enables the writing of filesystem meta-data to the swapcache.  Filesystem
50 metadata is any data which the filesystem accesses via the disk device
51 using buffercache.  Meta-data is cached globally regardless of file
52 or directory flags.
53 .Pp
54 .Cd vm.swapcache.data_enable
55 enables the writing of filesystem file-data to the swapcache.  Filesystem
56 filedata is any data which the filesystem accesses via a regular file.
57 In technical terms, when the buffer cache is used to access a regular
58 file through its vnode.  Please do not blindly turn on this option,
59 see the PERFORMANCE TUNING section for more information.
60 .Pp
61 .Cd vm.swapcache.use_chflags
62 enables the use of the
63 .Cm cache
64 and
65 .Cm noscache
66 .Xr chflags 1
67 flags to control which files will be data-cached.
68 If this sysctl is disabled and data_enable is enabled,
69 the system will ignore file flags and attempt to swapcache all
70 regular files.
71 .Pp
72 .Cd vm.swapcache.read_enable
73 enables reading from the swapcache and should be set to 1 for normal
74 operation.
75 .Pp
76 .Cd vm.swapcache.maxfilesize
77 controls which files are to be cached based on their size.
78 If set to non-zero only files smaller than the specified size
79 will be cached.  Larger files will not be cached.
80 .Sh PERFORMANCE TUNING
81 Best operation is achieved when the active data set fits within the
82 swapcache.
83 .Pp
84 .Bl -tag -width 4n -compact
85 .It Cd vm.swapcache.accrate
86 This specifies the burst accumulation rate in bytes per second and
87 ultimately controls the write bandwidth to swap averaged over a long
88 period of time.
89 This parameter must be carefully chosen to manage the write endurance of
90 the SSD in order to avoid wearing it out too quickly.
91 Even though SSDs have limited write endurance, there is massive
92 cost/performance benefit to using one in a swapcache configuration.
93 .Pp
94 Let's use the Intel X25V 40G MLC SATA SSD as an example.  This device
95 has approximately a 40TB (40 terabyte) write endurance.
96 Limiting the long term average bandwidth to 100K/sec leads to no more
97 than ~9G/day writing which calculates approximately to a 12 year
98 endurance.
99 Endurance scales linearly with size.  The 80G version of this SSD
100 will have a write endurance of approximately 80TB.
101 .Pp
102 MLC SSDs have approximately a 1000x write endurance, while the
103 lower density higher-cost SLC SSDs have an approximately 10000x
104 write endurance.  MLC SSDs can be used for the swapcache (and swap)
105 as long as the system manager is cognizant of its limitations.
106 .Pp
107 .It Cd vm.swapcache.meta_enable
108 Turning on just
109 .Cd meta_enable
110 causes only filesystem meta-data to be cached and will result
111 in very fast directory operations even over millions of inodes
112 and even in the face of other invasive operations being run
113 by other processes.
114 .Pp
115 .It Cd vm.swapcache.data_enable
116 Turning on
117 .Cd data_enable
118 (with or without other features) allows bulk file data to be
119 cached.
120 This feature is very useful for web server operation when the
121 operational data set fits in swap.
122 The usefulness is somewhat mitigated by the maximum number
123 of vnodes supported by the system via
124 .Cd kern.maxfiles ,
125 because the bulk data in the cache is lost when the related
126 vnode is recycled.  In this case it might be desireable to
127 take the plunge into running a 64-bit kernel which can support
128 far more vnodes.  32-bit kernels have limited kernel virtual
129 memory (KVM) and cannot reliably support more than around
130 100,000 active vnodes.  64-bit kernels can support 300,000+
131 active vnodes.
132 .Pp
133 Data caching is definitely more wasteful of SSD write bandwidth
134 than meta-data caching.  It doesn't hurt performance per se,
135 but may cause the
136 .Nm
137 to exhaust its burst and smack against the long term average
138 bandwidth limit, causing the SSD to wear out at the maximum rate you
139 programmed.  Data caching is far less wasteful and more efficient
140 if (on a 64-bit system only) you provide a sufficiently large SSD and
141 increase
142 .Cd kern.maxvnodes
143 to cover the entire directory topology being served.
144 Each vnode requires about 1K of physical ram.
145 .Pp
146 When data caching is turned on you generally want to use
147 .Xr chflags 1
148 with the
149 .Cm cache
150 flag to enable data caching on a directory.
151 This flag is tracked by the namecache and does not need to be
152 recursively set in the directory tree.
153 Simply setting the flag in a top level directory is sufficient.
154 A typical setup is something like this:
155 .Pp
156 .Dl chflags cache /etc /sbin /bin /usr /home
157 .Dl chflags noscache /usr/obj
158 .Pp
159 Alternatively if you have NFS mounts where chflags does not work you
160 can enable caching in some parent directory, then selectively disable
161 it.
162 .Pp
163 .Dl chflags cache /
164 .Dl chflags noscache /usr/obj /tmp /var/tmp
165 .Pp
166 If that doesn't work you can turn off
167 .Cd vm.swapcache.use_chflags
168 entirely and not bother with any chflagging.
169 .Pp
170 .It Cd vm.swapcache.maxfilesize
171 This may be used to reduce cache thrashing when a focus on a small
172 potentially fragmented filespace is desired, leaving the
173 larger files alone.
174 .Pp
175 .It Cd vm.swapcache.minburst
176 This controls hysteresis and prevents nickel-and-dime write bursting.
177 Once
178 .Cd curburst
179 drops to zero, writing to the swapcache ceases until it has recovered
180 past
181 .Cd minburst .
182 The idea here is to avoid creating a heavily fragmented swapcache where
183 reading data from a file must alternate between the cache and the primary
184 filesystem.  Doing so does not save disk seeks on the primary filesystem
185 so we want to avoid doing small bursts.  This parameter allows us to do
186 larger bursts.
187 The larger bursts also tend to improve SSD performance as the SSD itself
188 can do a better job write-combining and erasing blocks.
189 .Pp
190 .It Cd vm_swapcache.maxswappct
191 This controls the maximum amount of swapspace
192 .Nm
193 may use, in percentage terms.
194 .El
195 .Pp
196 Finally, interleaved swap (multiple SSDs) may be used to increase
197 performance even further.  A single SATA SSD is typically capable of
198 reading 120-220MB/sec.  Configuring two SSDs for your swap will
199 improve aggregate swapcache read performance by 1.5x to 1.8x.
200 In tests with two Intel 40G SSDs 300MB/sec was easily achieved.
201 .Pp
202 At this point you will be configuring more swap space than a 32 bit
203 .Dx
204 kernel can handle (due to KVM limitations).  By default, 32 bit
205 .Dx
206 systems only support 32G of configured swap and while this limit
207 can be increased somewhat in
208 .Pa /boot/loader.conf
209 you should really be using a 64-bit
210 .Dx
211 kernel instead.  64-bit systems support up to 512G of swap by default
212 and can be boosted to up to 8TB if you are really crazy and have enough ram.
213 Each 1GB of swap requires around 1MB of physical memory to manage it so
214 the practical limit is more around 1TB of swap.
215 .Pp
216 Of course, a 1TB SSD is something on the order of $3000+ as of this writing.
217 Even though a 1TB configuration might not be cost effective, storage levels
218 more in the 100-200G range certainly are.  If the machine has only a 1GigE
219 ethernet (100MB/s) there's no point configuring it for more SSD bandwidth.
220 A single SSD of the desired size would be sufficient.
221 .Sh INITIAL BURSTING & REPEATED BURSTING
222 Even though the average write bandwidth is limited it is desireable
223 to have a large initial burst after boot to load the cache.
224 .Cd curburst
225 is initialized to 4GB by default and you can force rebursting
226 by adjusting it with a sysctl.
227 Remember that
228 .Cd curburst
229 dynamically tracks burst and will go up and down depending.
230 .Pp
231 In addition there will be periods of time where the system is in
232 steady state and not writing to the swapcache.  During these periods
233 .Cd curburst
234 will inch back up but will not exceed
235 .Cd maxburst .
236 Thus the
237 .Cd maxburst
238 value controls how large a repeated burst can be.
239 .Pp
240 A second bursting parameter called
241 .Cd vm.swapcache.minburst
242 controls bursting when the maximum write bandwidth has been reached.
243 When
244 .Cd minburst
245 reaches zero write activity ceases and
246 .Cd curburst
247 is allowed to recover up to
248 .Cd minburst
249 before write activity resumes.  The recommended range for the
250 .Cd minburst
251 parameter is 1MB to 50MB.  This parameter has a relationship to
252 how fragmented the swapcache gets when not in a steady state.
253 Large bursts reduce fragmentation and reduce incidences of
254 excessive seeking on the hard drive.  If set too low the
255 swapcache will become fragmented within a single regular file
256 and the constant back-and-forth between the swapcache and the
257 hard drive will result in excessive seeking on the hard drive.
258 .Sh SWAPCACHE SIZE & MANAGEMENT
259 The swapcache feature will use up to 75% of configured swap space
260 by default.
261 The remaining 25% is reserved for normal paging operation.
262 The system operator should configure at least 4 times the SWAP space
263 versus main memory and no less than 8G of swap space.
264 If a 40G SSD is used the recommendation is to configure 16G to 32G of
265 swap (note: 32-bit is limited to 32G of swap by default, for 64-bit
266 it is 512G of swap).
267 .Pp
268 The
269 .Cd vm_swapcache.maxswappct
270 sysctl may be used to change the default.
271 You may have to change this default if you also use
272 .Xr tmpfs 5 ,
273 .Xr vn 4 ,
274 or if you have not allocated enough swap for reasonable normal paging
275 activity to occur (in which case you probably shouldn't be using
276 .Nm
277 anyway).
278 .Pp
279 If swapcache reaches the 75% limit it will begin tearing down swap
280 in linear bursts by iterating through available VM objects, until
281 swap space use drops to 70%.  The tear-down is limited by the rate at
282 which new data is written and this rate in turn is often limited
283 by
284 .Cd vm.swapcache.accrate ,
285 resulting in an orderly replacement of cached data and meta-data.
286 The limit is typically only reached when doing full data+meta-data
287 caching with no file size limitations and serving primarily large
288 files, or (on a 64-bit system) bumping kern.maxvnodes up to very
289 high values.
290 .Sh NORMAL SWAP PAGING ACTIVITY WITH SSD SWAP
291 This is not a function of
292 .Nm
293 per se but instead a normal function of the system.  Most systems have
294 sufficient memory that they do not need to page memory to swap.  These
295 types of systems are the ones best suited for MLC SSD configured swap
296 running with a
297 .Nm
298 configuration.
299 Systems which modestly page to swap, in the range of a few hundred
300 megabytes a day worth of writing, are also well suited for MLC SSD
301 configured swap.  Desktops usually fall into this category even if they
302 page out a bit more because swap activity is governed by the actions of
303 a single person.
304 .Pp
305 Systems which page anonymous memory heavily when
306 .Nm
307 would otherwise be turned off are not usually well suited for MLC SSD
308 configured swap.  Heavy paging activity is not governed by
309 .Nm
310 bandwidth control parameters and can lead to excessive uncontrolled
311 writing to the MLC SSD, causing premature wearout.  You would have to
312 use the lower density, more expensive SLC SSD technology (which has 10x
313 the durability).  This isn't to say that
314 .Nm
315 would be ineffective, just that the aggregate write bandwidth required
316 to support the system would be too large for MLC flash technologies.
317 .Pp
318 With this caveat in mind, SSD based paging on systems with insufficient
319 ram can be extremely effective in extending the useful life of the system.
320 For example, a system with a measly 192MB of ram and SSD swap can run
321 a -j 8 parallel build world in a little less than twice the time it
322 would take if the system had 2G of ram, whereas it would take 5x to 10x
323 as long with normal HD based swap.
324 .Sh WARNINGS
325 SSDs have limited durability and
326 .Nm
327 parameters should be carefully chosen to avoid early wearout.
328 For example, the Intel X25V 40G SSD has a nominal 40TB (terabyte)
329 write durability.
330 Generally speaking, you want to select parameters that will give you
331 at least 5 years of service life.  10 years is a good compromise.
332 .Pp
333 Durability typically scales with size and also depends on the
334 wear-leveling algorithm used by the device.  Durability can often
335 be improved by configuring less space (in a manufacturer-fresh drive)
336 than the drive's capacity.  For example, by only using 32G of a 40G
337 SSD.  SSDs typically implement 10% more storage than advertised and
338 use this storage to improve wear leveling.  As cells begin to fail
339 this overallotment slowly becomes part of the primary storage
340 until it has been exhausted.  After that the SSD has basically failed.
341 Keep in mind that if you use a larger portion of the SSD's advertised
342 storage the SSD will not know if/when you decide to use less unless
343 appropriate TRIM commands are sent (if supported), or a low level
344 factory erase is issued.
345 .Pp
346 The swapcache is designed for use with SSDs configured as swap and
347 will generally not improve performance when a normal hard drive is used
348 for swap.
349 .Pp
350 .Nm smartctl
351 (from pkgsrc's sysutils/smartmontools) may be used to retrieve 
352 the wear indicator from the drive.
353 One usually runs something like 'smartctl -d sat -a /dev/daXX'
354 (for AHCI/SILI/SCSI), or 'smartctl -a /dev/adXX' for NATA.  Many SSDs
355 will brick the SATA port when smart operations are done while the drive
356 is busy with normal activity, so the tool should only be run when the
357 SSD is idle.
358 .Pp
359 ID 232 (0xe8) in the SMART data dump indicates available reserved
360 space and ID 233 (0xe9) is the wear-out meter.  Reserved space
361 typically starts at 100 and decrements to 10, after which the SSD
362 is considered to operate in a degraded mode.  The wear-out meter
363 typically starts at 99 and decrements to 0, after which the SSD
364 has failed.
365 Wear on SSDs is a function only of the write durability which is
366 essentially just the total aggregate sectors written.
367 .Nm
368 tends to use large 64K writes as well as operates in a bursty fashion
369 which the SSD is able to take significant advantage of.
370 Power-on hours, power cycles, and read operations do not really affect wear.
371 .Pp
372 SSD's with MLC-based flash technology are high-density, low-cost solutions
373 with limited write durability.  SLC-based flash technology is a low-density,
374 higher-cost solution with 10x the write durability as MLC.  The durability
375 also scales with the amount of flash storage, with SLC based flash typically
376 twice as expensive per gigabyte.  From a cost perspective, SLC based flash
377 is at least 5x more cost effective in situations where high write
378 bandwidths are required (lasting 10x longer).  MLC is at least 2x more
379 cost effective in situations where high write bandwidth is not required.
380 When wear calculations are in years, these differences become huge.
381 .Nm
382 is usable with both technologies.
383 .Sh SEE ALSO
384 .Xr swapon 8 ,
385 .Xr fstab 5
386 .Sh HISTORY
387 .Nm
388 first appeared in
389 .Dx 2.5 .
390 .Sh AUTHORS
391 .An Matthew Dillon