1 ===========================================================================
3 IBM "Hypervisor Virtual Console Server" Installation Guide
4 for Linux Kernel 2.6.4+
5 Copyright (C) 2004 IBM Corporation
7 ===========================================================================
8 NOTE:Eight space tabs are the optimum editor setting for reading this file.
9 ===========================================================================
11 Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
12 Date Created: March, 02, 2004
13 Last Changed: July, 07, 2004
15 ---------------------------------------------------------------------------
18 1. Driver Introduction:
19 2. System Requirements
27 8. Questions & Answers:
30 ---------------------------------------------------------------------------
31 1. Driver Introduction:
33 This is the device driver for the IBM Hypervisor Virtual Console Server,
34 "hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
35 space applications access to the system consoles of logically partitioned
36 operating systems (Linux and AIX) running on the same partitioned Power5
37 ppc64 system. Physical hardware consoles per partition are not practical
38 on this hardware so system consoles are accessed by this driver using
39 firmware interfaces to virtual terminal devices.
41 ---------------------------------------------------------------------------
42 2. System Requirements:
44 This device driver was written using 2.6.4 Linux kernel APIs and will only
45 build and run on kernels of this version or later.
47 This driver was written to operate solely on IBM Power5 ppc64 hardware
48 though some care was taken to abstract the architecture dependent firmware
49 calls from the driver code.
51 Sysfs must be mounted on the system so that the user can determine which
52 major and minor numbers are associated with each vty-server. Directions
53 for sysfs mounting are outside the scope of this document.
55 ---------------------------------------------------------------------------
58 The hvcs driver registers itself as a tty driver. The tty layer
59 dynamically allocates a block of major and minor numbers in a quantity
60 requested by the registering driver. The hvcs driver asks the tty layer
61 for 64 of these major/minor numbers by default to use for hvcs device node
64 If the default number of device entries is adequate then this driver can be
65 built into the kernel. If not, the default can be over-ridden by inserting
66 the driver as a module with insmod parameters.
68 ---------------------------------------------------------------------------
71 The following menuconfig example demonstrates selecting to build this
72 driver into the kernel.
75 Character devices --->
76 <*> IBM Hypervisor Virtual Console Server Support
78 Begin the kernel make process.
80 ---------------------------------------------------------------------------
83 The following menuconfig example demonstrates selecting to build this
84 driver as a kernel module.
87 Character devices --->
88 <M> IBM Hypervisor Virtual Console Server Support
90 The make process will build the following kernel modules:
95 To insert the module with the default allocation execute the following
96 commands in the order they appear:
101 The hvcserver module contains architecture specific firmware calls and must
102 be inserted first, otherwise the hvcs module will not find some of the
105 To override the default use an insmod parameter as follows (requesting 4
106 tty devices as an example):
108 insmod hvcs.ko hvcs_parm_num_devs=4
110 There is a maximum number of dev entries that can be specified on insmod.
111 We think that 1024 is currently a decent maximum number of server adapters
112 to allow. This can always be changed by modifying the constant in the
113 source file before building.
115 NOTE: The length of time it takes to insmod the driver seems to be related
116 to the number of tty interfaces the registering driver requests.
118 In order to remove the driver module execute the following command:
122 The recommended method for installing hvcs as a module is to use depmod to
123 build a current modules.dep file in /lib/modules/`uname -r` and then
126 modprobe hvcs hvcs_parm_num_devs=4
128 The modules.dep file indicates that hvcserver.ko needs to be inserted
129 before hvcs.ko and modprobe uses this file to smartly insert the modules in
132 The following modprobe command is used to remove hvcs and hvcserver in the
137 ---------------------------------------------------------------------------
140 The tty layer creates sysfs entries which contain the major and minor
141 numbers allocated for the hvcs driver. The following snippet of "tree"
142 output of the sysfs directory shows where these numbers are presented:
145 |-- *other sysfs base dirs*
148 | |-- *other classes of devices*
151 | |-- *other tty devices*
162 | |-- *other tty devices*
164 |-- *other sysfs base dirs*
166 For the above examples the following output is a result of cat'ing the
167 "dev" entry in the hvcs directory:
169 Pow5:/sys/class/tty/hvcs0/ # cat dev
172 Pow5:/sys/class/tty/hvcs1/ # cat dev
175 Pow5:/sys/class/tty/hvcs2/ # cat dev
178 Pow5:/sys/class/tty/hvcs3/ # cat dev
181 The output from reading the "dev" attribute is the char device major and
182 minor numbers that the tty layer has allocated for this driver's use. Most
183 systems running hvcs will already have the device entries created or udev
184 will do it automatically.
186 Given the example output above, to manually create a /dev/hvcs* node entry
187 mknod can be used as follows:
189 mknod /dev/hvcs0 c 254 0
190 mknod /dev/hvcs1 c 254 1
191 mknod /dev/hvcs2 c 254 2
192 mknod /dev/hvcs3 c 254 3
194 Using mknod to manually create the device entries makes these device nodes
195 persistent. Once created they will exist prior to the driver insmod.
197 Attempting to connect an application to /dev/hvcs* prior to insertion of
198 the hvcs module will result in an error message similar to the following:
200 "/dev/hvcs*: No such device".
202 NOTE: Just because there is a device node present doesn't mean that there
203 is a vty-server device configured for that node.
205 ---------------------------------------------------------------------------
208 Since this driver controls devices that provide a tty interface a user can
209 interact with the device node entries using any standard tty-interactive
210 method (e.g. "cat", "dd", "echo"). The intent of this driver however, is
211 to provide real time console interaction with a Linux partition's console,
212 which requires the use of applications that provide bi-directional,
213 interactive I/O with a tty device.
215 Applications (e.g. "minicom" and "screen") that act as terminal emulators
216 or perform terminal type control sequence conversion on the data being
217 passed through them are NOT acceptable for providing interactive console
218 I/O. These programs often emulate antiquated terminal types (vt100 and
219 ANSI) and expect inbound data to take the form of one of these supported
220 terminal types but they either do not convert, or do not _adequately_
221 convert, outbound data into the terminal type of the terminal which invoked
222 them (though screen makes an attempt and can apparently be configured with
223 much termcap wrestling.)
225 For this reason kermit and cu are two of the recommended applications for
226 interacting with a Linux console via an hvcs device. These programs simply
227 act as a conduit for data transfer to and from the tty device. They do not
228 require inbound data to take the form of a particular terminal type, nor do
229 they cook outbound data to a particular terminal type.
231 In order to ensure proper functioning of console applications one must make
232 sure that once connected to a /dev/hvcs console that the console's $TERM
233 env variable is set to the exact terminal type of the terminal emulator
234 used to launch the interactive I/O application. If one is using xterm and
235 kermit to connect to /dev/hvcs0 when the console prompt becomes available
236 one should "export TERM=xterm" on the console. This tells ncurses
237 applications that are invoked from the console that they should output
238 control sequences that xterm can understand.
240 As a precautionary measure an hvcs user should always "exit" from their
241 session before disconnecting an application such as kermit from the device
242 node. If this is not done, the next user to connect to the console will
243 continue using the previous user's logged in session which includes
244 using the $TERM variable that the previous user supplied.
246 ---------------------------------------------------------------------------
249 As a security feature to prevent the delivery of stale data to an
250 unintended target the Power5 system firmware disables the fetching of data
251 and discards that data when a connection between a vty-server and a vty has
252 been severed. As an example, when a vty-server is immediately disconnected
253 from a vty following output of data to the vty the vty adapter may not have
254 enough time between when it received the data interrupt and when the
255 connection was severed to fetch the data from firmware before the fetch is
256 disabled by firmware.
258 When hvcs is being used to serve consoles this behavior is not a huge issue
259 because the adapter stays connected for large amounts of time following
260 almost all data writes. When hvcs is being used as a tty conduit to tunnel
261 data between two partitions [see Q & A below] this is a huge problem
262 because the standard Linux behavior when cat'ing or dd'ing data to a device
263 is to open the tty, send the data, and then close the tty. If this driver
264 manually terminated vty-server connections on tty close this would close
265 the vty-server and vty connection before the target vty has had a chance to
268 Additionally, disconnecting a vty-server and vty only on module removal or
269 adapter removal is impractical because other vty-servers in other
270 partitions may require the usage of the target vty at any time.
272 Due to this behavioral restriction disconnection of vty-servers from the
273 connected vty is a manual procedure using a write to a sysfs attribute
274 outlined below, on the other hand the initial vty-server connection to a
275 vty is established automatically by this driver. Manual vty-server
276 connection is never required.
278 In order to terminate the connection between a vty-server and vty the
279 "vterm_state" sysfs attribute within each vty-server's sysfs entry is used.
280 Reading this attribute reveals the current connection state of the
281 vty-server adapter. A zero means that the vty-server is not connected to a
282 vty. A one indicates that a connection is active.
284 Writing a '0' (zero) to the vterm_state attribute will disconnect the VTERM
285 connection between the vty-server and target vty ONLY if the vterm_state
286 previously read '1'. The write directive is ignored if the vterm_state
287 read '0' or if any value other than '0' was written to the vterm_state
288 attribute. The following example will show the method used for verifying
289 the vty-server connection status and disconnecting a vty-server connection.
291 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
294 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state
296 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
299 All vty-server connections are automatically terminated when the device is
300 hotplug removed and when the module is removed.
302 ---------------------------------------------------------------------------
305 Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
306 is symlinked in several other sysfs tree directories, notably under the
307 hvcs driver entry, which looks like the following example:
309 Pow5:/sys/bus/vio/drivers/hvcs # ls
310 . .. 30000003 30000004 rescan
312 By design, firmware notifies the hvcs driver of vty-server lifetimes and
313 partner vty removals but not the addition of partner vtys. Since an HMC
314 Super Admin can add partner info dynamically we have provided the hvcs
315 driver sysfs directory with the "rescan" update attribute which will query
316 firmware and update the partner info for all the vty-servers that this
317 driver manages. Writing a '1' to the attribute triggers the update. An
318 explicit example follows:
320 Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan
322 Reading the attribute will indicate a state of '1' or '0'. A one indicates
323 that an update is in process. A zero indicates that an update has
324 completed or was never executed.
326 Vty-server entries in this directory are a 32 bit partition unique unit
327 address that is created by firmware. An example vty-server sysfs entry
328 looks like the following:
330 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
331 . current_vty devspec partner_clcs vterm_state
332 .. detach_state name partner_vtys
334 Each entry is provided, by default with a "name" attribute. Reading the
335 "name" attribute will reveal the device type as shown in the following
338 Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
341 Each entry is also provided, by default, with a "devspec" attribute which
342 reveals the full device specification when read, as shown in the following
345 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
346 /vdevice/vty-server@30000004
348 Each vty-server sysfs dir is provided with two read-only attributes that
349 provide lists of easily parsed partner vty data: "partner_vtys" and
352 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
359 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcs
360 U5112.428.103048A-V3-C0
361 U5112.428.103048A-V3-C2
362 U5112.428.103048A-V3-C3
363 U5112.428.103048A-V4-C0
364 U5112.428.103048A-V5-C0
366 Reading partner_vtys returns a list of partner vtys. Vty unit address
367 numbering is only per-partition-unique so entries will frequently repeat.
369 Reading partner_clcs returns a list of "converged location codes" which are
370 composed of a system serial number followed by "-V*", where the '*' is the
371 target partition number, and "-C*", where the '*' is the slot of the
372 adapter. The first vty partner corresponds to the first clc item, the
373 second vty partner to the second clc item, etc.
375 A vty-server can only be connected to a single vty at a time. The entry,
376 "current_vty" prints the clc of the currently selected partner vty when
379 The current_vty can be changed by writing a valid partner clc to the entry
380 as in the following example:
382 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
383 8A-V4-C0 > current_vty
385 Changing the current_vty when a vty-server is already connected to a vty
386 does not affect the current connection. The change takes effect when the
387 currently open connection is freed.
389 Information on the "vterm_state" attribute was covered earlier on the
390 chapter entitled "disconnection".
392 ---------------------------------------------------------------------------
393 8. Questions & Answers:
394 ===========================================================================
395 Q: What are the security concerns involving hvcs?
397 A: There are three main security concerns:
399 1. The creator of the /dev/hvcs* nodes has the ability to restrict
400 the access of the device entries to certain users or groups. It
401 may be best to create a special hvcs group privilege for providing
402 access to system consoles.
404 2. To provide network security when grabbing the console it is
405 suggested that the user connect to the console hosting partition
406 using a secure method, such as SSH or sit at a hardware console.
408 3. Make sure to exit the user session when done with a console or
409 the next vty-server connection (which may be from another
410 partition) will experience the previously logged in session.
412 ---------------------------------------------------------------------------
413 Q: How do I multiplex a console that I grab through hvcs so that other
416 A: You can use "screen" to directly connect to the /dev/hvcs* device and
417 setup a session on your machine with the console group privileges. As
418 pointed out earlier by default screen doesn't provide the termcap settings
419 for most terminal emulators to provide adequate character conversion from
420 term type "screen" to others. This means that curses based programs may
421 not display properly in screen sessions.
423 ---------------------------------------------------------------------------
424 Q: Why are the colors all messed up?
425 Q: Why are the control characters acting strange or not working?
426 Q: Why is the console output all strange and unintelligible?
428 A: Please see the preceding section on "Connection" for a discussion of how
429 applications can affect the display of character control sequences.
430 Additionally, just because you logged into the console using and xterm
431 doesn't mean someone else didn't log into the console with the HMC console
432 (vt320) before you and leave the session logged in. The best thing to do
433 is to export TERM to the terminal type of your terminal emulator when you
434 get the console. Additionally make sure to "exit" the console before you
435 disconnect from the console. This will ensure that the next user gets
436 their own TERM type set when they login.
438 ---------------------------------------------------------------------------
439 Q: When I try to CONNECT kermit to an hvcs device I get:
440 "Sorry, can't open connection: /dev/hvcs*"What is happening?
442 A: Some other Power5 console mechanism has a connection to the vty and
443 isn't giving it up. You can try to force disconnect the consoles from the
444 HMC by right clicking on the partition and then selecting "close terminal".
445 Otherwise you have to hunt down the people who have console authority. It
446 is possible that you already have the console open using another kermit
447 session and just forgot about it. Please review the console options for
448 Power5 systems to determine the many ways a system console can be held.
452 A: Another user may not have a connectivity method currently attached to a
453 /dev/hvcs device but the vterm_state may reveal that they still have the
454 vty-server connection established. They need to free this using the method
455 outlined in the section on "Disconnection" in order for others to connect
460 A: The user profile you are using to execute kermit probably doesn't have
461 permissions to use the /dev/hvcs* device.
465 A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*
466 entry still exists (on systems without udev).
470 A: There is not a corresponding vty-server device that maps to an existing
473 ---------------------------------------------------------------------------
474 Q: When I try to CONNECT kermit to an hvcs device I get:
475 "Sorry, write access to UUCP lockfile directory denied."
477 A: The /dev/hvcs* entry you have specified doesn't exist where you said it
478 does? Maybe you haven't inserted the module (on systems with udev).
480 ---------------------------------------------------------------------------
481 Q: If I already have one Linux partition installed can I use hvcs on said
482 partition to provide the console for the install of a second Linux
485 A: Yes granted that your are connected to the /dev/hvcs* device using
486 kermit or cu or some other program that doesn't provide terminal emulation.
488 ---------------------------------------------------------------------------
489 Q: Can I connect to more than one partition's console at a time using this
492 A: Yes. Of course this means that there must be more than one vty-server
493 configured for this partition and each must point to a disconnected vty.
495 ---------------------------------------------------------------------------
496 Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
498 A: Yes, if you have dlpar and hotplug enabled for your system and it has
499 been built into the kernel the hvcs drivers is configured to dynamically
500 handle additions of new devices and removals of unused devices.
502 ---------------------------------------------------------------------------
503 Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
504 device on that partition as the other end of the pipe?
506 A: Yes, on Power5 platforms the hvc_console driver provides a tty interface
507 for extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).
508 In order to get a tty conduit working between the two partitions the HMC
509 Super Admin must create an additional "serial server" for the target
510 partition with the HMC gui which will show up as /dev/hvc* when the target
511 partition is rebooted.
513 The HMC Super Admin then creates an additional "serial client" for the
514 current partition and points this at the target partition's newly created
515 "serial server" adapter (remember the slot). This shows up as an
516 additional /dev/hvcs* device.
518 Now a program on the target system can be configured to read or write to
519 /dev/hvc* and another program on the current partition can be configured to
520 read or write to /dev/hvcs*. Now you have a tty conduit between two
523 ---------------------------------------------------------------------------
526 The proper channel for reporting bugs is either through the Linux OS
527 distribution company that provided your OS or by posting issues to the
528 ppc64 development mailing list at:
530 linuxppc64-dev@lists.linuxppc.org
532 This request is to provide a documented and searchable public exchange
533 of the problems and solutions surrounding this driver for the benefit of