aoeping.8 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  1. .TH aoeping 8
  2. .SH NAME
  3. aoeping \- simple communication with AoE device
  4. .SH SYNOPSIS
  5. .B aoeping [options] {shelf} {slot} {netif}
  6. .fi
  7. .SH DESCRIPTION
  8. The
  9. .IR aoeping (8)
  10. program performs simple one or two-round-trip communication with an
  11. ATA over Ethernet (AoE) device.
  12. .PP
  13. Running
  14. .IR aoeping (8)
  15. without command line arguments will result in a
  16. short usage summary being displayed.
  17. .PP
  18. The
  19. .IR aoeping (8)
  20. program will wait forever if if doesn't receive
  21. an expected response. The caller should use a time out to catch
  22. this situation.
  23. .SS Arguments
  24. .TP
  25. \fBshelf\fP
  26. This should be the shelf address (major AoE address) of the AoE device
  27. to communicate with.
  28. .TP
  29. \fBslot\fP
  30. This should be the slot address (minor AoE address) of the AoE device
  31. to communicate with.
  32. .TP
  33. \fBnetif\fP
  34. The name of the ethernet network interface to use for AoE
  35. communications, e.g., eth1.
  36. .SS Options
  37. .TP
  38. \fB-i\fP
  39. Issue an ATA "identify device" command after receiving the AoE
  40. device's Config
  41. Query response. The "ident" response will be printed on standard
  42. output as a hexidecimal dump.
  43. .TP
  44. \fB-I\fP
  45. Issue an ATA "identify device" command after receiving the AoE
  46. device's Config
  47. Query response. The "ident" response will be pretty-printed on standard
  48. output as selected human-readable fields.
  49. .TP
  50. \fB-v\fP
  51. Turn on
  52. more copious output, including a hexidecimal dump of the Config Query
  53. response from the AoE device (see AoE spec at URL below).
  54. .TP
  55. \fB-s\fP
  56. This option takes an argument. The
  57. argument is a decimal integer that specifies the number of seconds
  58. that
  59. .IR aoeping (8)
  60. will wait for a response before timing out and
  61. exiting with a non-zero status.
  62. .TP
  63. \fB-S\fP
  64. This option takes an argument. The
  65. argument is the name of a SMART command to send to the disk. The
  66. SMART commands in the list below are supported. If the command
  67. requires data
  68. transfer, one sector (512 bytes) of data is always the amount
  69. transfered. If the command takes a parameter (for the Low LBA
  70. register), then the name of the SMART command is immediately followed
  71. by a colon and then a number, the value of the parameter, e.g., "-S
  72. read_log:1".
  73. .IP
  74. read_data
  75. offline_immediate
  76. read_log
  77. write_log
  78. enable
  79. disable
  80. return_status
  81. For \fBwrite_log\fP,
  82. .IR aoeping (8)
  83. reads from
  84. standard input the one sector of data to be
  85. written to the specified log.
  86. The
  87. .IR aoeping (8)
  88. command just sends and receives SMART commands, without
  89. interpreting them. See the ATA specification for more information on
  90. using SMART.
  91. .LP
  92. .TP
  93. \fB-t\fP
  94. (This is an advanced feature.) This option has an argument. The
  95. argument is a decimal integer that is used as the initial tag, with
  96. the highest bit set, as
  97. the
  98. first tag in ATA commands. Tags for subsequent ATA commands will be
  99. incremented by one.
  100. .TP
  101. \fB-h\fP
  102. Show a usage summary.
  103. .SH EXAMPLE
  104. In this example, the root user
  105. uses
  106. .IR aoeping (8)
  107. to check for the presence of aoe device e10.9 on
  108. network interface eth0.
  109. .IP
  110. .EX
  111. .nf
  112. bash# aoeping -v 10 9 eth0 | head
  113. tag: 80000000
  114. eth: eth0
  115. shelf: 10
  116. slot: 9
  117. config query response:
  118. 00 0d 87 aa c9 00 00 10 04 00 11 1f 88 a2 18 00
  119. 00 0a 09 01 00 00 00 00 00 03 30 08 00 10 00 04
  120. 66 6f 6f 0a 00 ff ff ff ff ff ff ff ff ff ff ff
  121. ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
  122. ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
  123. .fi
  124. .EE
  125. .LP
  126. The next example shows root making sure the disk on the e10.9 is still
  127. responsive by issuing an ATA device identify command with a 20-second
  128. timeout.
  129. .IP
  130. .EX
  131. .nf
  132. bash# aoeping -i -s 20 \\
  133. 10 9 eth0 > /dev/null \\
  134. && echo ok
  135. ok
  136. .fi
  137. .EE
  138. .LP
  139. The next example uses SMART to determine whether the disk on e10.9
  140. thinks it
  141. has exceeded its error threshold. The ATA spec says that the LBA Mid
  142. register will be 0x4f when the disk has not exceeded its error
  143. threshold.
  144. .IP
  145. .EX
  146. .nf
  147. bash# aoeping -S return_status \\
  148. 10 9 eth0 | grep 'LBA Mid: 0x4f' \\
  149. > /dev/null \\
  150. && echo ok
  151. ok
  152. .fi
  153. .EE
  154. .LP
  155. Note that in a script, it would be prudent to specify and handle a
  156. timeout. Also, a good script would make sure the
  157. \fBStatus\fP register does not have the error bit (bit zero) or the
  158. device fault bit (bit 5) set.
  159. .SH "SEE ALSO"
  160. .IR aoe-discover (8),
  161. .IR aoe-interfaces (8),
  162. .IR aoe-mkdevs (8),
  163. .IR aoe-mkshelf (8),
  164. .IR aoe-stat (8),
  165. \fIAoE (ATA over Ethernet)\fP: http://www.coraid.com/documents/AoEr10.txt,
  166. \fIATA specification\fP
  167. .SH AUTHOR
  168. Ed L. Cashin (ecashin@coraid.com)