diff options
Diffstat (limited to 'doc/sg_sanitize.8')
| -rw-r--r-- | doc/sg_sanitize.8 | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/doc/sg_sanitize.8 b/doc/sg_sanitize.8 new file mode 100644 index 00000000..bb7bdc4d --- /dev/null +++ b/doc/sg_sanitize.8 @@ -0,0 +1,267 @@ +.TH SG_SANITIZE "8" "December 2020" "sg3_utils\-1.46" SG3_UTILS +.SH NAME +sg_sanitize \- remove all user data from disk with SCSI SANITIZE command +.SH SYNOPSIS +.B sg_sanitize +[\fI\-\-ause\fR] [\fI\-\-block\fR] [\fI\-\-count=OC\fR] [\fI\-\-crypto\fR] +[\fI\-\-dry\-run\fR] [\fI\-\-desc\fR] [\fI\-\-early\fR] [\fI\-\-fail\fR] +[\fI\-\-help\fR] [\fI\-\-invert\fR] [\fI\-\-ipl=LEN\fR] [\fI\-\-overwrite\fR] +[\fI\-\-pattern=PF\fR] [\fI\-\-quick\fR] [\fI\-\-test=TE\fR] +[\fI\-\-timeout=SECS\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] +[\fI\-\-wait\fR] [\fI\-\-zero\fR] [\fI\-\-znr\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +This utility invokes the SCSI SANITIZE command. This command was first +introduced in the SBC\-3 revision 27 draft. The purpose of the sanitize +operation is to alter the information in the cache and on the medium of a +logical unit (e.g. a disk) so that the recovery of user data is not +possible. If that user data cannot be erased, or is in the process of +being erased, then the sanitize operation prevents access to that user +data. +.PP +Once a SCSI SANITIZE command has successfully started, then user data from +that disk is no longer available. Even if the disk is power cycled, the +sanitize operation will continue after power is re\-instated until it is +complete. +.PP +This utility requires either the \fI\-\-block\fR, \fI\-\-crypto\fR, +\fI\-\-fail\fR or \fI\-\-overwrite\fR option. With the \fI\-\-block\fR, +\fI\-\-crypto\fR or \fI\-\-overwrite\fR option the user is given 15 seconds +to reconsider whether they wish to erase all the data on a disk, unless +the \fI\-\-quick\fR option is given in which case the sanitize operation +starts immediately. The disk's INQUIRY response strings are printed out just +in case the wrong \fIDEVICE\fR has been given. +.PP +If the \fI\-\-early\fR option is given then this utility will exit soon +after starting the SANITIZE command with the IMMED bit set. The user can +monitor the progress of the sanitize operation with +the "sg_requests \-\-num=9999 \-\-progress" which sends a REQUEST SENSE +command every 30 seconds. Otherwise if the \fI\-\-wait\fR option is given +then this utility will wait until the SANITIZE command completes (or fails) +and that can be many hours. +.PP +If the \fI\-\-wait\fR option is not given then the SANITIZE command is +started with the IMMED bit set. If neither the \fI\-\-early\fR nor the +\fI\-\-wait\fR options are given then this utility sends a REQUEST SENSE +command after every 60 seconds until there are no more progress indications +in which case this utility exits silently. If additionally the +\fI\-\-verbose\fR option is given the exit will be marked by a short +message that the sanitize seems to have succeeded. +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +The options are arranged in alphabetical order based on the long +option name. +.TP +\fB\-A\fR, \fB\-\-ause\fR +sets the AUSE bit in the cdb. AUSE is an acronym for "allow unrestricted +sanitize exit". The default action is to leave the AUSE bit cleared. +.TP +\fB\-B\fR, \fB\-\-block\fR +perform a "block erase" sanitize operation. +.TP +\fB\-c\fR, \fB\-\-count\fR=\fIOC\fR +where \fIOC\fR is the "overwrite count" associated with the "overwrite" +sanitize operation. \fIOC\fR can be a value between 1 and 31 and 1 is +the default. +.TP +\fB\-C\fR, \fB\-\-crypto\fR +perform a "cryptographic erase" sanitize operation. Note that this erase is +often very quick as it simply overwrites an internal cryptographic key with +a new value. Those keys are not accessible to users and encrypt all data +written then decrypt all data read from the media. The primary reason for +doing that is to make this operation fast. This operation can not be +reversed. +.TP +\fB\-d\fR, \fB\-\-desc\fR +sets the DESC field in the REQUEST SENSE command used for polling. By +default this field is set to zero. A REQUEST SENSE polling loop is +used after the SANITIZE command is issued (assuming that neither the +\fI\-\-early\fR nor the \fI\-\-wait\fR option have been given) to check +on the progress of this command as it can take some time. +.TP +\fB\-D\fR, \fB\-\-dry\-run\fR +this option will parse the command line, do all the preparation but bypass +the actual SANITIZE command. +.TP +\fB\-e\fR, \fB\-\-early\fR +the default action of this utility is to poll the disk every 60 seconds to +fetch the progress indication until the sanitize is finished. When this +option is given this utility will exit "early" as soon as the SANITIZE +command with the IMMED bit set to 1 has been acknowledged. This option and +\fI\-\-wait\fR cannot both be given. +.TP +\fB\-F\fR, \fB\-\-fail\fR +perform an "exit failure mode" sanitize operation. Typically requires the +preceding SANITIZE command to have set the AUSE bit. +.TP +\fB\-h\fR, \fB\-\-help\fR +print out the usage information then exit. +.TP +\fB\-i\fR, \fB\-\-ipl\fR=\fILEN\fR +set the initialization pattern length to \fILEN\fR bytes. By default it is +set to the length of the pattern file (\fIPF\fR) or 4 if the \fI\-\-zero\fR +option is given. Only active when the \fI\-\-overwrite\fR option is also +given. It is the number of bytes from the \fIPF\fR file that will be used +as the initialization pattern (if the \fI\-\-zero\fR option is not given). +The minimum size is 1 byte and the maximum is the logical block size of the +\fIDEVICE\fR (and not to exceed 65535). If \fILEN\fR exceeds the \fIPF\fR +file size then the initialization pattern is padded with zeros. +.TP +\fB\-I\fR, \fB\-\-invert\fR +set the INVERT bit in the overwrite service action parameter list. This +only affects the "overwrite" sanitize operation. The default is a clear +INVERT bit. When the INVERT bit is set then the initialization pattern +is inverted between consecutive overwrite passes. +.TP +\fB\-O\fR, \fB\-\-overwrite\fR +perform an "overwrite" sanitize operation. When this option is given then +the \fI\-\-pattern=PF\fR or the \fI\-\-zero\fR option is required. +.TP +\fB\-p\fR, \fB\-\-pattern\fR=\fIPF\fR +where \fIPF\fR is the filename of a file containing the initialization +pattern required by an "overwrite" sanitize operation. The length of +this file will be used as the length of the initialization pattern unless +the \fI\-\-ipl=LEN\fR option is given. The length of the initialization +pattern must be from 1 to the logical block size of the \fIDEVICE\fR. +.TP +\fB\-Q\fR, \fB\-\-quick\fR +the default action (i.e. when the option is not given) is to give the user +15 seconds to reconsider doing a sanitize operation on the \fIDEVICE\fR. +When this option is given that step (i.e. the 15 second warning period) +is skipped. +.TP +\fB\-T\fR, \fB\-\-test\fR=\fITE\fR +set the TEST field in the overwrite service action parameter list. This +only affects the "overwrite" sanitize operation. The default is to place +0 in that field. +.TP +\fB\-t\fR, \fB\-\-timeout\fR=\fISECS\fR +where \fISECS\fR is the number of seconds used for the timeout on the +SANITIZE command. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase the level of verbosity, (i.e. debug output). +.TP +\fB\-V\fR, \fB\-\-version\fR +print the version string and then exit. +.TP +\fB\-w\fR, \fB\-\-wait\fR +the default action (i.e. without this option and the \fI\-\-early\fR option) +is to start the SANITIZE command with the IMMED bit set then poll for the +progress indication with the REQUEST SENSE command until the sanitize +operation is complete (or fails). When this option is given (and the +\fI\-\-early\fR option is not given) then the SANITIZE command is started +with the IMMED bit clear. For a large disk this might take hours. [A +cryptographic erase operation could potentially be very quick.] +.TP +\fB\-z\fR, \fB\-\-zero\fR +with an "overwrite" sanitize operation this option causes the initialization +pattern to be zero (4 zeros are used as the initialization pattern). Cannot +be used with the \fI\-\-pattern=PF\fR option. If this option is given +twice (e.g. '\-zz') then 0xff is used as the initialization byte. +.TP +\fB\-Z\fR, \fB\-\-znr\fR +sets ZNR bit (zoned no reset) in cdb. Introduced in the SBC\-4 revision 7 +draft. +.SH NOTES +The SCSI SANITIZE command is closely related to the ATA SANITIZE command, +both are relatively new with the ATA command being the first one defined. +The SCSI to ATA Translation (SAT) definition for the SCSI SANITIZE command +appeared in the SAT\-3 revision 4 draft. +.PP +When a SAT layer is used to a (S)ATA disk then for OVERWRITE the +initialization pattern must be 4 bytes long. So this means either the +\fI\-\-zero\fR option may be given, or a pattern file (with the +\fI\-\-pattern=PF\fR option) that is 4 bytes long or set to that +length with the \fI\-\-ipl=LEN\fR option. +.PP +The SCSI SANITIZE command is related to the SCSI FORMAT UNIT command. It +is likely that a block erase sanitize operation would take a similar +amount of time as a format on the same disk (e.g. 9 hours for a 2 Terabyte +disk). The primary goal of a format is the configuration of the disk at +the end of a format (e.g. different logical block size or protection +information added). Removal of user data is only a side effect of a format. +With the SCSI SANITIZE command, removal of user data is the primary goal. +If a sanitize operation is interrupted (e.g. the disk is power cycled) +then after power up any remaining user data will not be available and the +sanitize operation will continue. When a format is interrupted (e.g. the +disk is power cycled) the drafts say very little about the state of the +disk. In practice some of the original user data may remain and the format +may need to be restarted. +.PP +Finding out whether a disk (SCSI or ATA) supports SANITIZE can be a +challenge. If the user really needs to find out and no other information +is available then try 'sg_sanitize \-\-fail \-vvv <device>' and observe +the sense data returned may be the safest approach. Using the \fI\-\-fail\fR +variant of this utility should have no effect unless it follows an already +failed sanitize operation. If the SCSI REPORT SUPPORTED OPERATION CODES +command (see sg_opcodes) is supported then using it would be a better +approach for finding if sanitize is supported. +.PP +If using the dd command to check the before and after data of a particular +block (i.e. check the erase actually worked) it is a good idea to use +the 'iflag=direct' operand. Otherwise the first read might be cached and +returned when the same LBA is read a little later. Obviously this utility +should only be used to sanitize data on a disk whose mounted file +systems (if any) have been unmounted prior to the erase! +.SH EXAMPLES +These examples use Linux device names. For suitable device names in +other supported Operating Systems see the sg3_utils(8) man page. +.PP +As a precaution if this utility is called with no options then apart from +printing a usage message, nothing happens: +.PP + sg_sanitize /dev/sdm +.PP +To do a "block erase" sanitize the \fI\-\-block\fR option is required. +The user will be given a 15 second period to reconsider, the SCSI SANITIZE +command will be started with the IMMED bit set, then this utility will +poll for a progress indication with a REQUEST SENSE command until the +sanitize operation is finished: +.PP + sg_sanitize \-\-block /dev/sdm +.PP +To start a "block erase" sanitize and return from this utility once it is +started (but not yet completed) use the \fI\-\-early\fR option: +.PP + sg_sanitize \-\-block \-\-early /dev/sdm +.PP +If the 15 second reconsideration time is not required add the +\fI\-\-quick\fR option: +.PP + sg_sanitize \-\-block \-\-quick \-\-early /dev/sdm +.PP +To do an "overwrite" sanitize a pattern file may be given: +.PP + sg_sanitize \-\-overwrite \-\-pattern=rand.img /dev/sdm +.PP +If the length of that "rand.img" is 512 bytes (a typically logical block +size) then to use only the first 17 bytes (repeatedly) in the "overwrite" +sanitize operation: +.PP + sg_sanitize \-\-overwrite \-\-pattern=rand.img \-\-ipl=17 /dev/sdm +.PP +To overwrite with zeros use: + sg_sanitize \-\-overwrite \-\-zero /dev/sdm +.SH EXIT STATUS +The exit status of sg_sanitize is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. Unless the \fI\-\-wait\fR option is given, the +exit status may not reflect the success of otherwise of the format. +.PP +The Unix convention is that "no news is good news" but that can be a bit +unnerving after an operation like sanitize, especially if it finishes +quickly (i.e. before the first progress poll is sent). Giving the +\fI\-\-verbose\fR option once should supply enough additional output to +settle those nerves. +.SH AUTHORS +Written by Douglas Gilbert. +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2011\-2020 Douglas Gilbert +.br +This software is distributed under a BSD\-2\-Clause license. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sg_requests(8), sg_format(8) |