hvcs.rst 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581
  1. ===============================================================
  2. HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
  3. ===============================================================
  4. for Linux Kernel 2.6.4+
  5. Copyright (C) 2004 IBM Corporation
  6. .. ===========================================================================
  7. .. NOTE:Eight space tabs are the optimum editor setting for reading this file.
  8. .. ===========================================================================
  9. Author(s): Ryan S. Arnold <rsa@us.ibm.com>
  10. Date Created: March, 02, 2004
  11. Last Changed: August, 24, 2004
  12. .. Table of contents:
  13. 1. Driver Introduction:
  14. 2. System Requirements
  15. 3. Build Options:
  16. 3.1 Built-in:
  17. 3.2 Module:
  18. 4. Installation:
  19. 5. Connection:
  20. 6. Disconnection:
  21. 7. Configuration:
  22. 8. Questions & Answers:
  23. 9. Reporting Bugs:
  24. 1. Driver Introduction:
  25. =======================
  26. This is the device driver for the IBM Hypervisor Virtual Console Server,
  27. "hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
  28. space applications access to the system consoles of logically partitioned
  29. operating systems (Linux and AIX) running on the same partitioned Power5
  30. ppc64 system. Physical hardware consoles per partition are not practical
  31. on this hardware so system consoles are accessed by this driver using
  32. firmware interfaces to virtual terminal devices.
  33. 2. System Requirements:
  34. =======================
  35. This device driver was written using 2.6.4 Linux kernel APIs and will only
  36. build and run on kernels of this version or later.
  37. This driver was written to operate solely on IBM Power5 ppc64 hardware
  38. though some care was taken to abstract the architecture dependent firmware
  39. calls from the driver code.
  40. Sysfs must be mounted on the system so that the user can determine which
  41. major and minor numbers are associated with each vty-server. Directions
  42. for sysfs mounting are outside the scope of this document.
  43. 3. Build Options:
  44. =================
  45. The hvcs driver registers itself as a tty driver. The tty layer
  46. dynamically allocates a block of major and minor numbers in a quantity
  47. requested by the registering driver. The hvcs driver asks the tty layer
  48. for 64 of these major/minor numbers by default to use for hvcs device node
  49. entries.
  50. If the default number of device entries is adequate then this driver can be
  51. built into the kernel. If not, the default can be over-ridden by inserting
  52. the driver as a module with insmod parameters.
  53. 3.1 Built-in:
  54. -------------
  55. The following menuconfig example demonstrates selecting to build this
  56. driver into the kernel::
  57. Device Drivers --->
  58. Character devices --->
  59. <*> IBM Hypervisor Virtual Console Server Support
  60. Begin the kernel make process.
  61. 3.2 Module:
  62. -----------
  63. The following menuconfig example demonstrates selecting to build this
  64. driver as a kernel module::
  65. Device Drivers --->
  66. Character devices --->
  67. <M> IBM Hypervisor Virtual Console Server Support
  68. The make process will build the following kernel modules:
  69. - hvcs.ko
  70. - hvcserver.ko
  71. To insert the module with the default allocation execute the following
  72. commands in the order they appear::
  73. insmod hvcserver.ko
  74. insmod hvcs.ko
  75. The hvcserver module contains architecture specific firmware calls and must
  76. be inserted first, otherwise the hvcs module will not find some of the
  77. symbols it expects.
  78. To override the default use an insmod parameter as follows (requesting 4
  79. tty devices as an example)::
  80. insmod hvcs.ko hvcs_parm_num_devs=4
  81. There is a maximum number of dev entries that can be specified on insmod.
  82. We think that 1024 is currently a decent maximum number of server adapters
  83. to allow. This can always be changed by modifying the constant in the
  84. source file before building.
  85. NOTE: The length of time it takes to insmod the driver seems to be related
  86. to the number of tty interfaces the registering driver requests.
  87. In order to remove the driver module execute the following command::
  88. rmmod hvcs.ko
  89. The recommended method for installing hvcs as a module is to use depmod to
  90. build a current modules.dep file in /lib/modules/`uname -r` and then
  91. execute::
  92. modprobe hvcs hvcs_parm_num_devs=4
  93. The modules.dep file indicates that hvcserver.ko needs to be inserted
  94. before hvcs.ko and modprobe uses this file to smartly insert the modules in
  95. the proper order.
  96. The following modprobe command is used to remove hvcs and hvcserver in the
  97. proper order::
  98. modprobe -r hvcs
  99. 4. Installation:
  100. ================
  101. The tty layer creates sysfs entries which contain the major and minor
  102. numbers allocated for the hvcs driver. The following snippet of "tree"
  103. output of the sysfs directory shows where these numbers are presented::
  104. sys/
  105. |-- *other sysfs base dirs*
  106. |
  107. |-- class
  108. | |-- *other classes of devices*
  109. | |
  110. | `-- tty
  111. | |-- *other tty devices*
  112. | |
  113. | |-- hvcs0
  114. | | `-- dev
  115. | |-- hvcs1
  116. | | `-- dev
  117. | |-- hvcs2
  118. | | `-- dev
  119. | |-- hvcs3
  120. | | `-- dev
  121. | |
  122. | |-- *other tty devices*
  123. |
  124. |-- *other sysfs base dirs*
  125. For the above examples the following output is a result of cat'ing the
  126. "dev" entry in the hvcs directory::
  127. Pow5:/sys/class/tty/hvcs0/ # cat dev
  128. 254:0
  129. Pow5:/sys/class/tty/hvcs1/ # cat dev
  130. 254:1
  131. Pow5:/sys/class/tty/hvcs2/ # cat dev
  132. 254:2
  133. Pow5:/sys/class/tty/hvcs3/ # cat dev
  134. 254:3
  135. The output from reading the "dev" attribute is the char device major and
  136. minor numbers that the tty layer has allocated for this driver's use. Most
  137. systems running hvcs will already have the device entries created or udev
  138. will do it automatically.
  139. Given the example output above, to manually create a /dev/hvcs* node entry
  140. mknod can be used as follows::
  141. mknod /dev/hvcs0 c 254 0
  142. mknod /dev/hvcs1 c 254 1
  143. mknod /dev/hvcs2 c 254 2
  144. mknod /dev/hvcs3 c 254 3
  145. Using mknod to manually create the device entries makes these device nodes
  146. persistent. Once created they will exist prior to the driver insmod.
  147. Attempting to connect an application to /dev/hvcs* prior to insertion of
  148. the hvcs module will result in an error message similar to the following::
  149. "/dev/hvcs*: No such device".
  150. NOTE: Just because there is a device node present doesn't mean that there
  151. is a vty-server device configured for that node.
  152. 5. Connection
  153. =============
  154. Since this driver controls devices that provide a tty interface a user can
  155. interact with the device node entries using any standard tty-interactive
  156. method (e.g. "cat", "dd", "echo"). The intent of this driver however, is
  157. to provide real time console interaction with a Linux partition's console,
  158. which requires the use of applications that provide bi-directional,
  159. interactive I/O with a tty device.
  160. Applications (e.g. "minicom" and "screen") that act as terminal emulators
  161. or perform terminal type control sequence conversion on the data being
  162. passed through them are NOT acceptable for providing interactive console
  163. I/O. These programs often emulate antiquated terminal types (vt100 and
  164. ANSI) and expect inbound data to take the form of one of these supported
  165. terminal types but they either do not convert, or do not _adequately_
  166. convert, outbound data into the terminal type of the terminal which invoked
  167. them (though screen makes an attempt and can apparently be configured with
  168. much termcap wrestling.)
  169. For this reason kermit and cu are two of the recommended applications for
  170. interacting with a Linux console via an hvcs device. These programs simply
  171. act as a conduit for data transfer to and from the tty device. They do not
  172. require inbound data to take the form of a particular terminal type, nor do
  173. they cook outbound data to a particular terminal type.
  174. In order to ensure proper functioning of console applications one must make
  175. sure that once connected to a /dev/hvcs console that the console's $TERM
  176. env variable is set to the exact terminal type of the terminal emulator
  177. used to launch the interactive I/O application. If one is using xterm and
  178. kermit to connect to /dev/hvcs0 when the console prompt becomes available
  179. one should "export TERM=xterm" on the console. This tells ncurses
  180. applications that are invoked from the console that they should output
  181. control sequences that xterm can understand.
  182. As a precautionary measure an hvcs user should always "exit" from their
  183. session before disconnecting an application such as kermit from the device
  184. node. If this is not done, the next user to connect to the console will
  185. continue using the previous user's logged in session which includes
  186. using the $TERM variable that the previous user supplied.
  187. Hotplug add and remove of vty-server adapters affects which /dev/hvcs* node
  188. is used to connect to each vty-server adapter. In order to determine which
  189. vty-server adapter is associated with which /dev/hvcs* node a special sysfs
  190. attribute has been added to each vty-server sysfs entry. This entry is
  191. called "index" and showing it reveals an integer that refers to the
  192. /dev/hvcs* entry to use to connect to that device. For instance cating the
  193. index attribute of vty-server adapter 30000004 shows the following::
  194. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
  195. 2
  196. This index of '2' means that in order to connect to vty-server adapter
  197. 30000004 the user should interact with /dev/hvcs2.
  198. It should be noted that due to the system hotplug I/O capabilities of a
  199. system the /dev/hvcs* entry that interacts with a particular vty-server
  200. adapter is not guaranteed to remain the same across system reboots. Look
  201. in the Q & A section for more on this issue.
  202. 6. Disconnection
  203. ================
  204. As a security feature to prevent the delivery of stale data to an
  205. unintended target the Power5 system firmware disables the fetching of data
  206. and discards that data when a connection between a vty-server and a vty has
  207. been severed. As an example, when a vty-server is immediately disconnected
  208. from a vty following output of data to the vty the vty adapter may not have
  209. enough time between when it received the data interrupt and when the
  210. connection was severed to fetch the data from firmware before the fetch is
  211. disabled by firmware.
  212. When hvcs is being used to serve consoles this behavior is not a huge issue
  213. because the adapter stays connected for large amounts of time following
  214. almost all data writes. When hvcs is being used as a tty conduit to tunnel
  215. data between two partitions [see Q & A below] this is a huge problem
  216. because the standard Linux behavior when cat'ing or dd'ing data to a device
  217. is to open the tty, send the data, and then close the tty. If this driver
  218. manually terminated vty-server connections on tty close this would close
  219. the vty-server and vty connection before the target vty has had a chance to
  220. fetch the data.
  221. Additionally, disconnecting a vty-server and vty only on module removal or
  222. adapter removal is impractical because other vty-servers in other
  223. partitions may require the usage of the target vty at any time.
  224. Due to this behavioral restriction disconnection of vty-servers from the
  225. connected vty is a manual procedure using a write to a sysfs attribute
  226. outlined below, on the other hand the initial vty-server connection to a
  227. vty is established automatically by this driver. Manual vty-server
  228. connection is never required.
  229. In order to terminate the connection between a vty-server and vty the
  230. "vterm_state" sysfs attribute within each vty-server's sysfs entry is used.
  231. Reading this attribute reveals the current connection state of the
  232. vty-server adapter. A zero means that the vty-server is not connected to a
  233. vty. A one indicates that a connection is active.
  234. Writing a '0' (zero) to the vterm_state attribute will disconnect the VTERM
  235. connection between the vty-server and target vty ONLY if the vterm_state
  236. previously read '1'. The write directive is ignored if the vterm_state
  237. read '0' or if any value other than '0' was written to the vterm_state
  238. attribute. The following example will show the method used for verifying
  239. the vty-server connection status and disconnecting a vty-server connection::
  240. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
  241. 1
  242. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state
  243. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
  244. 0
  245. All vty-server connections are automatically terminated when the device is
  246. hotplug removed and when the module is removed.
  247. 7. Configuration
  248. ================
  249. Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
  250. is symlinked in several other sysfs tree directories, notably under the
  251. hvcs driver entry, which looks like the following example::
  252. Pow5:/sys/bus/vio/drivers/hvcs # ls
  253. . .. 30000003 30000004 rescan
  254. By design, firmware notifies the hvcs driver of vty-server lifetimes and
  255. partner vty removals but not the addition of partner vtys. Since an HMC
  256. Super Admin can add partner info dynamically we have provided the hvcs
  257. driver sysfs directory with the "rescan" update attribute which will query
  258. firmware and update the partner info for all the vty-servers that this
  259. driver manages. Writing a '1' to the attribute triggers the update. An
  260. explicit example follows:
  261. Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan
  262. Reading the attribute will indicate a state of '1' or '0'. A one indicates
  263. that an update is in process. A zero indicates that an update has
  264. completed or was never executed.
  265. Vty-server entries in this directory are a 32 bit partition unique unit
  266. address that is created by firmware. An example vty-server sysfs entry
  267. looks like the following::
  268. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
  269. . current_vty devspec name partner_vtys
  270. .. index partner_clcs vterm_state
  271. Each entry is provided, by default with a "name" attribute. Reading the
  272. "name" attribute will reveal the device type as shown in the following
  273. example::
  274. Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
  275. vty-server
  276. Each entry is also provided, by default, with a "devspec" attribute which
  277. reveals the full device specification when read, as shown in the following
  278. example::
  279. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
  280. /vdevice/vty-server@30000004
  281. Each vty-server sysfs dir is provided with two read-only attributes that
  282. provide lists of easily parsed partner vty data: "partner_vtys" and
  283. "partner_clcs"::
  284. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
  285. 30000000
  286. 30000001
  287. 30000002
  288. 30000000
  289. 30000000
  290. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcs
  291. U5112.428.103048A-V3-C0
  292. U5112.428.103048A-V3-C2
  293. U5112.428.103048A-V3-C3
  294. U5112.428.103048A-V4-C0
  295. U5112.428.103048A-V5-C0
  296. Reading partner_vtys returns a list of partner vtys. Vty unit address
  297. numbering is only per-partition-unique so entries will frequently repeat.
  298. Reading partner_clcs returns a list of "converged location codes" which are
  299. composed of a system serial number followed by "-V*", where the '*' is the
  300. target partition number, and "-C*", where the '*' is the slot of the
  301. adapter. The first vty partner corresponds to the first clc item, the
  302. second vty partner to the second clc item, etc.
  303. A vty-server can only be connected to a single vty at a time. The entry,
  304. "current_vty" prints the clc of the currently selected partner vty when
  305. read.
  306. The current_vty can be changed by writing a valid partner clc to the entry
  307. as in the following example::
  308. Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
  309. 8A-V4-C0 > current_vty
  310. Changing the current_vty when a vty-server is already connected to a vty
  311. does not affect the current connection. The change takes effect when the
  312. currently open connection is freed.
  313. Information on the "vterm_state" attribute was covered earlier on the
  314. chapter entitled "disconnection".
  315. 8. Questions & Answers:
  316. =======================
  317. Q: What are the security concerns involving hvcs?
  318. A: There are three main security concerns:
  319. 1. The creator of the /dev/hvcs* nodes has the ability to restrict
  320. the access of the device entries to certain users or groups. It
  321. may be best to create a special hvcs group privilege for providing
  322. access to system consoles.
  323. 2. To provide network security when grabbing the console it is
  324. suggested that the user connect to the console hosting partition
  325. using a secure method, such as SSH or sit at a hardware console.
  326. 3. Make sure to exit the user session when done with a console or
  327. the next vty-server connection (which may be from another
  328. partition) will experience the previously logged in session.
  329. ---------------------------------------------------------------------------
  330. Q: How do I multiplex a console that I grab through hvcs so that other
  331. people can see it:
  332. A: You can use "screen" to directly connect to the /dev/hvcs* device and
  333. setup a session on your machine with the console group privileges. As
  334. pointed out earlier by default screen doesn't provide the termcap settings
  335. for most terminal emulators to provide adequate character conversion from
  336. term type "screen" to others. This means that curses based programs may
  337. not display properly in screen sessions.
  338. ---------------------------------------------------------------------------
  339. Q: Why are the colors all messed up?
  340. Q: Why are the control characters acting strange or not working?
  341. Q: Why is the console output all strange and unintelligible?
  342. A: Please see the preceding section on "Connection" for a discussion of how
  343. applications can affect the display of character control sequences.
  344. Additionally, just because you logged into the console using and xterm
  345. doesn't mean someone else didn't log into the console with the HMC console
  346. (vt320) before you and leave the session logged in. The best thing to do
  347. is to export TERM to the terminal type of your terminal emulator when you
  348. get the console. Additionally make sure to "exit" the console before you
  349. disconnect from the console. This will ensure that the next user gets
  350. their own TERM type set when they login.
  351. ---------------------------------------------------------------------------
  352. Q: When I try to CONNECT kermit to an hvcs device I get:
  353. "Sorry, can't open connection: /dev/hvcs*"What is happening?
  354. A: Some other Power5 console mechanism has a connection to the vty and
  355. isn't giving it up. You can try to force disconnect the consoles from the
  356. HMC by right clicking on the partition and then selecting "close terminal".
  357. Otherwise you have to hunt down the people who have console authority. It
  358. is possible that you already have the console open using another kermit
  359. session and just forgot about it. Please review the console options for
  360. Power5 systems to determine the many ways a system console can be held.
  361. OR
  362. A: Another user may not have a connectivity method currently attached to a
  363. /dev/hvcs device but the vterm_state may reveal that they still have the
  364. vty-server connection established. They need to free this using the method
  365. outlined in the section on "Disconnection" in order for others to connect
  366. to the target vty.
  367. OR
  368. A: The user profile you are using to execute kermit probably doesn't have
  369. permissions to use the /dev/hvcs* device.
  370. OR
  371. A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*
  372. entry still exists (on systems without udev).
  373. OR
  374. A: There is not a corresponding vty-server device that maps to an existing
  375. /dev/hvcs* entry.
  376. ---------------------------------------------------------------------------
  377. Q: When I try to CONNECT kermit to an hvcs device I get:
  378. "Sorry, write access to UUCP lockfile directory denied."
  379. A: The /dev/hvcs* entry you have specified doesn't exist where you said it
  380. does? Maybe you haven't inserted the module (on systems with udev).
  381. ---------------------------------------------------------------------------
  382. Q: If I already have one Linux partition installed can I use hvcs on said
  383. partition to provide the console for the install of a second Linux
  384. partition?
  385. A: Yes granted that your are connected to the /dev/hvcs* device using
  386. kermit or cu or some other program that doesn't provide terminal emulation.
  387. ---------------------------------------------------------------------------
  388. Q: Can I connect to more than one partition's console at a time using this
  389. driver?
  390. A: Yes. Of course this means that there must be more than one vty-server
  391. configured for this partition and each must point to a disconnected vty.
  392. ---------------------------------------------------------------------------
  393. Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
  394. A: Yes, if you have dlpar and hotplug enabled for your system and it has
  395. been built into the kernel the hvcs drivers is configured to dynamically
  396. handle additions of new devices and removals of unused devices.
  397. ---------------------------------------------------------------------------
  398. Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
  399. after a reboot. What happened?
  400. A: Assignment of vty-server adapters to /dev/hvcs* entries is always done
  401. in the order that the adapters are exposed. Due to hotplug capabilities of
  402. this driver assignment of hotplug added vty-servers may be in a different
  403. order than how they would be exposed on module load. Rebooting or
  404. reloading the module after dynamic addition may result in the /dev/hvcs*
  405. and vty-server coupling changing if a vty-server adapter was added in a
  406. slot between two other vty-server adapters. Refer to the section above
  407. on how to determine which vty-server goes with which /dev/hvcs* node.
  408. Hint; look at the sysfs "index" attribute for the vty-server.
  409. ---------------------------------------------------------------------------
  410. Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
  411. device on that partition as the other end of the pipe?
  412. A: Yes, on Power5 platforms the hvc_console driver provides a tty interface
  413. for extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).
  414. In order to get a tty conduit working between the two partitions the HMC
  415. Super Admin must create an additional "serial server" for the target
  416. partition with the HMC gui which will show up as /dev/hvc* when the target
  417. partition is rebooted.
  418. The HMC Super Admin then creates an additional "serial client" for the
  419. current partition and points this at the target partition's newly created
  420. "serial server" adapter (remember the slot). This shows up as an
  421. additional /dev/hvcs* device.
  422. Now a program on the target system can be configured to read or write to
  423. /dev/hvc* and another program on the current partition can be configured to
  424. read or write to /dev/hvcs*. Now you have a tty conduit between two
  425. partitions.
  426. ---------------------------------------------------------------------------
  427. 9. Reporting Bugs:
  428. ==================
  429. The proper channel for reporting bugs is either through the Linux OS
  430. distribution company that provided your OS or by posting issues to the
  431. PowerPC development mailing list at:
  432. linuxppc-dev@lists.ozlabs.org
  433. This request is to provide a documented and searchable public exchange
  434. of the problems and solutions surrounding this driver for the benefit of
  435. all users.