aoeping.8 4.6 KB

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