Edit a SCSI Mode Page with sg_wr_mode

sg_wr_mode reads one SCSI mode page, changes selected bytes, and writes the result back to the device. The examples leave the device's saved settings alone unless you explicitly add --save. Allow 15 to 30 minutes, plus a maintenance window if the device is serving live I/O.

This guide uses sg3-utils package version 1.46-3ubuntu4. On this machine the installed program reports 1.26 20180628, while its manual page identifies the sg3_utils 1.43 documentation. Check your own output before relying on version-specific details.

1. Identify the device and command

• Needs. A SCSI device path, the sg3-utils package, and permission to issue MODE SENSE and MODE SELECT commands.
• MODE SELECT changes device state. Do not experiment against a disk, tape drive or optical drive that is carrying important data, and do not guess a device path.

$ command -v sg_wr_mode
/usr/bin/sg_wr_mode
$ sg_wr_mode --version
sg_wr_mode: version: 1.26 20180628
$ ls -l /dev/sgX
crw-rw---- 1 root disk ... /dev/sgX

Replace /dev/sgX in the rest of this guide with the generic SCSI device that corresponds to your hardware. An ordinary account can inspect the command and its documentation, but reading or writing the device usually requires membership of the device's group or elevated privileges.

2. Read one page without changing it

Choose a specific page code in hexadecimal. The page code must be between 0x00 and 0x3e; 0x3f, which means all pages, is deliberately rejected by sg_wr_mode. A subpage can be appended as PAGE,SUBPAGE. The example below reads the power condition page, commonly written as 1a:

$ sg_wr_mode --page=1a /dev/sgX
Mode data length=...
Block descriptor length=...
Mode page 0x1a, length=...
  ... hexadecimal bytes ...

With no --contents, the utility fetches the existing mode data and prints its header, block descriptors and selected page. It does not alter the device. Exact lengths and byte values are device-specific, so treat the output as a baseline rather than copying the sample text above.

If you need a file that can be edited, use sg_modes with its raw page output:

$ sg_modes --page=1a --raw /dev/sgX > mode-page-1a.txt
$ sed -n '1,40p' mode-page-1a.txt

Keep this original capture. It is your comparison point and, when the page is accepted by the device, your practical rollback input.

3. Change only the bytes you mean to change

• A contents string is a comma-separated list of hexadecimal byte values from 00 through ff.
• A mask lets you replace only selected bits: a set bit takes the corresponding bit from --contents; a clear bit keeps the current device value.

For example, the manual's power-condition example changes one byte from 28 to 37 while leaving the other seven bytes untouched:

$ sg_wr_mode --page=1a \
    --contents=00,00,00,00,00,00,00,37 \
    --mask=00,00,00,00,00,00,00,ff \
    /dev/sgX

The command reads the existing page first, merges the masked bytes, then sends MODE SELECT. The default command length is the 10-byte MODE SENSE and MODE SELECT variant. Use --six, equivalent to --len=6, only for an older device that requires the 6-byte commands.

Check the result by reading the same page again:

$ sg_modes --page=1a /dev/sgX
>> Power condition ..., page_control: current
 00     1a ... 37 ...

The page name, spacing and surrounding bytes vary. Confirm the intended field or byte changed and that unrelated bytes still match your baseline.

4. Decide whether the change should survive a reset

Without --save, a successful MODE SELECT changes the current page only. The device may restore its saved value after a reset or power cycle. Add --save when you have verified that the page is saveable and you explicitly want the new value stored:

$ sg_wr_mode --page=1a \
    --contents=00,00,00,00,00,00,00,37 \
    --mask=00,00,00,00,00,00,00,ff \
    --save /dev/sgX

Some pages cannot be saved. In that case the device should report an illegal field in the command. Do not treat --save as a harmless persistence switch: it changes the lifetime of the setting and may expose a device-specific limitation.

To undo the example, write the original value from your captured page with the same mask, first without --save if you only need to restore the current state. If the original setting was saved, use --save as well. Verify both current and saved values where the device supports those page controls.

5. Use the safer input format for a complete page

For a larger, carefully reviewed page, pass --contents=- and feed the edited bytes on standard input. Commas, spaces, tabs and newlines separate bytes, and a # starts a comment to the end of its line:

$ cp --preserve=all mode-page-1a.txt mode-page-1a.before-edit.txt
$ editor mode-page-1a.txt
$ sg_wr_mode --page=1a --contents=- --save /dev/sgX < mode-page-1a.txt

Review the file before the final command. The utility does not decide whether a byte is semantically changeable; the device performs that check. If the command reports Invalid field in parameter list or a parameter list length error, the page remains unaltered according to the SCSI error handling described by the manual. Re-read it rather than assuming the intended value was partly applied.

6. Avoid force and understand revert-to-defaults

• --force skips the checks that normally require the contents to match the existing page's length, page code and subpage code. It is intended for vendor-specific pages, cannot be combined with --mask, and the device can still reject the data. Use it only when you have a matching vendor specification and a recovery capture.
• --rtd is more disruptive: it sends MODE SELECT with the Revert To Defaults bit and ignores most other options. It can restore all current mode pages to their manufacturer defaults; adding --save also restores saved values. Older devices may not support this SPC-5 feature. Do not use it as a shortcut for undoing one byte.

$ sg_wr_mode --rtd /dev/sgX
$ printf 'exit status: %s\n' "$?"
exit status: 0

Exit status zero means the command completed successfully. It does not prove that a desired field has a particular value, so read the relevant page afterwards.