Read and Set a SCSI Device Timestamp with sg_timestamp

Every SCSI device keeps its own clock, and sg_timestamp is how you read it, decode where it came from, and set it when a device demands it. The examples use sg_timestamp 1.14 (20191220), supplied here by sg3-utils 1.46-3ubuntu4.

• Time needed: about fifteen minutes.
• What you need: a Linux shell, the sg3-utils package, and the correct SCSI device path.
• Privilege: reading a device may need access to its device node; setting its timestamp changes device state and may need elevated privileges.

Do not experiment with a disk that is handling production I/O.

1. Confirm the installed command

Check the executable, package and version before relying on examples. These are ordinary, read-only commands:

$ command -v sg_timestamp
/usr/bin/sg_timestamp
$ dpkg-query -W -f='${Package} ${Version}\n' sg3-utils
sg3-utils 1.46-3ubuntu4
$ sg_timestamp --version
version: 1.14 20191220

Option names and output can vary between releases. This guide follows the installed command and its local sg_timestamp(8) manual. If your version reports different help, use that help as the final authority for your host.

2. Read the timestamp without changing it

Without a set option, the program sends SCSI REPORT TIMESTAMP. Add --readonly so the device is opened read-only, and use --srep to ask for Unix-style seconds rather than the device's native milliseconds:

$ sg_timestamp --readonly --srep /dev/sgX
1448993950

Replace /dev/sgX with the generic SCSI device node for your target. Do not guess it from a partition name. Identify the device with your normal storage inventory first, then check the path exists:

$ test -c /dev/sgX && echo 'device node exists'
device node exists

The number is seconds since 1970-01-01 00:00:00 UTC. A successful command prints one value and exits with status 0. A device that does not implement REPORT TIMESTAMP returns an error instead; adding sudo cannot add a SCSI feature the device lacks.

3. Convert the value to a date

GNU date accepts an epoch value with --date=@.... Keep the command substitution separate so the value can be checked before it is displayed:

$ timestamp=$(sg_timestamp --readonly --srep /dev/sgX) && printf 'device seconds: %s\n' "$timestamp"
device seconds: 1448993950
$ date --date="@$timestamp"
Tue Dec  1 18:19:10 GMT 2015
$ date --date="@$timestamp" --rfc-email
Tue, 01 Dec 2015 18:19:10 +0000

Your local time zone changes the displayed clock time; the stored value is still UTC-based. For a script, test the exit status of sg_timestamp and validate that a value was returned before passing it to another command. Do not silently treat an empty result as the current time.

If you need the native representation, omit --srep. The report then prints milliseconds since the same epoch. The --milliseconds set option uses that unit too.

4. Inspect the timestamp origin

The report contains a timestamp origin field, but the normal output does not print it. Add --origin to decode it:

$ sg_timestamp --readonly --origin --srep /dev/sgX
timestamp origin: power up or hard reset
1448993950

The descriptive form identifies the most recent event that initialised the device clock:

• Value 0: power-up or hard-reset initialisation.
• Value 2: a previous SET TIMESTAMP operation.
• Value 3: another method.

Use --origin twice when you need the numeric field, or three times for a machine-readable line:

$ sg_timestamp --readonly --origin --origin --origin --no-timestamp /dev/sgX
TIMESTAMP_ORIGIN=2

--no-timestamp is useful here because it suppresses the timestamp value and leaves the origin line as the result to parse. Check your installed help if you build a parser around other verbosity or diagnostic output.

5. Save the old value before making a change

Setting the timestamp sends SCSI SET TIMESTAMP. It changes state in the device, not merely the output of this command. Before doing it, capture the current value so you have an exact recovery value:

$ old_seconds=$(sg_timestamp --readonly --srep /dev/sgX) && printf 'saved old value: %s\n' "$old_seconds"
saved old value: 1448993950

6. Set the device timestamp to now

Use --seconds with the current Unix time when the device expects second precision:

$ now=$(date +%s) && sudo sg_timestamp --seconds="$now" /dev/sgX
$ sudo sg_timestamp --readonly --srep /dev/sgX
1760000000

The second output is illustrative: it will be close to the value generated by date when you run the command. The program multiplies --seconds by 1000 before sending SET TIMESTAMP. Use --milliseconds=MS instead when you have a specific millisecond value to apply. The two set options are mutually exclusive.

Elevated privileges are only one possible requirement. The device, transport and enclosure may also reject SET TIMESTAMP. Treat a non-zero exit status as a failed change and inspect the device's error message.

7. Verify or recover the change

Read the value back after a successful set. Allow for the small delay between generating now and reading the device:

$ sudo sg_timestamp --readonly --srep /dev/sgX
1760000001
$ date --date="@1760000001" --rfc-email
Tue, 07 Oct 2025 08:53:21 +0000

If you need to undo the change, set the saved value explicitly. There is no general undo command because the previous timestamp is device-specific:

$ sudo sg_timestamp --seconds="$old_seconds" /dev/sgX
$ sudo sg_timestamp --readonly --srep /dev/sgX
1448993950

8. Handle useful diagnostics safely

• --hex prints the raw REPORT TIMESTAMP response in hexadecimal on standard error.
• --raw sends the binary response to standard output for another program to consume; it is not human-readable, ignores --origin and --srep, and sends diagnostics to standard error instead. Redirect it to a named file only once you have confirmed the destination will not overwrite useful data.
• --elapsed formats a reported value as days, hours, minutes, seconds and milliseconds. Use it when the device value represents elapsed time since an event such as a power cycle, not when you want a calendar date. Do not apply both interpretations to the same output.