582 lines · plain
1===============================================================2HVCS IBM "Hypervisor Virtual Console Server" Installation Guide3===============================================================4 5for Linux Kernel 2.6.4+6 7Copyright (C) 2004 IBM Corporation8 9.. ===========================================================================10.. NOTE:Eight space tabs are the optimum editor setting for reading this file.11.. ===========================================================================12 13 14Author(s): Ryan S. Arnold <rsa@us.ibm.com>15 16Date Created: March, 02, 200417Last Changed: August, 24, 200418 19.. Table of contents:20 21 1. Driver Introduction:22 2. System Requirements23 3. Build Options:24 3.1 Built-in:25 3.2 Module:26 4. Installation:27 5. Connection:28 6. Disconnection:29 7. Configuration:30 8. Questions & Answers:31 9. Reporting Bugs:32 331. Driver Introduction:34=======================35 36This is the device driver for the IBM Hypervisor Virtual Console Server,37"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user38space applications access to the system consoles of logically partitioned39operating systems (Linux and AIX) running on the same partitioned Power540ppc64 system. Physical hardware consoles per partition are not practical41on this hardware so system consoles are accessed by this driver using42firmware interfaces to virtual terminal devices.43 442. System Requirements:45=======================46 47This device driver was written using 2.6.4 Linux kernel APIs and will only48build and run on kernels of this version or later.49 50This driver was written to operate solely on IBM Power5 ppc64 hardware51though some care was taken to abstract the architecture dependent firmware52calls from the driver code.53 54Sysfs must be mounted on the system so that the user can determine which55major and minor numbers are associated with each vty-server. Directions56for sysfs mounting are outside the scope of this document.57 583. Build Options:59=================60 61The hvcs driver registers itself as a tty driver. The tty layer62dynamically allocates a block of major and minor numbers in a quantity63requested by the registering driver. The hvcs driver asks the tty layer64for 64 of these major/minor numbers by default to use for hvcs device node65entries.66 67If the default number of device entries is adequate then this driver can be68built into the kernel. If not, the default can be over-ridden by inserting69the driver as a module with insmod parameters.70 713.1 Built-in:72-------------73 74The following menuconfig example demonstrates selecting to build this75driver into the kernel::76 77 Device Drivers --->78 Character devices --->79 <*> IBM Hypervisor Virtual Console Server Support80 81Begin the kernel make process.82 833.2 Module:84-----------85 86The following menuconfig example demonstrates selecting to build this87driver as a kernel module::88 89 Device Drivers --->90 Character devices --->91 <M> IBM Hypervisor Virtual Console Server Support92 93The make process will build the following kernel modules:94 95 - hvcs.ko96 - hvcserver.ko97 98To insert the module with the default allocation execute the following99commands in the order they appear::100 101 insmod hvcserver.ko102 insmod hvcs.ko103 104The hvcserver module contains architecture specific firmware calls and must105be inserted first, otherwise the hvcs module will not find some of the106symbols it expects.107 108To override the default use an insmod parameter as follows (requesting 4109tty devices as an example)::110 111 insmod hvcs.ko hvcs_parm_num_devs=4112 113There is a maximum number of dev entries that can be specified on insmod.114We think that 1024 is currently a decent maximum number of server adapters115to allow. This can always be changed by modifying the constant in the116source file before building.117 118NOTE: The length of time it takes to insmod the driver seems to be related119to the number of tty interfaces the registering driver requests.120 121In order to remove the driver module execute the following command::122 123 rmmod hvcs.ko124 125The recommended method for installing hvcs as a module is to use depmod to126build a current modules.dep file in /lib/modules/`uname -r` and then127execute::128 129 modprobe hvcs hvcs_parm_num_devs=4130 131The modules.dep file indicates that hvcserver.ko needs to be inserted132before hvcs.ko and modprobe uses this file to smartly insert the modules in133the proper order.134 135The following modprobe command is used to remove hvcs and hvcserver in the136proper order::137 138 modprobe -r hvcs139 1404. Installation:141================142 143The tty layer creates sysfs entries which contain the major and minor144numbers allocated for the hvcs driver. The following snippet of "tree"145output of the sysfs directory shows where these numbers are presented::146 147 sys/148 |-- *other sysfs base dirs*149 |150 |-- class151 | |-- *other classes of devices*152 | |153 | `-- tty154 | |-- *other tty devices*155 | |156 | |-- hvcs0157 | | `-- dev158 | |-- hvcs1159 | | `-- dev160 | |-- hvcs2161 | | `-- dev162 | |-- hvcs3163 | | `-- dev164 | |165 | |-- *other tty devices*166 |167 |-- *other sysfs base dirs*168 169For the above examples the following output is a result of cat'ing the170"dev" entry in the hvcs directory::171 172 Pow5:/sys/class/tty/hvcs0/ # cat dev173 254:0174 175 Pow5:/sys/class/tty/hvcs1/ # cat dev176 254:1177 178 Pow5:/sys/class/tty/hvcs2/ # cat dev179 254:2180 181 Pow5:/sys/class/tty/hvcs3/ # cat dev182 254:3183 184The output from reading the "dev" attribute is the char device major and185minor numbers that the tty layer has allocated for this driver's use. Most186systems running hvcs will already have the device entries created or udev187will do it automatically.188 189Given the example output above, to manually create a /dev/hvcs* node entry190mknod can be used as follows::191 192 mknod /dev/hvcs0 c 254 0193 mknod /dev/hvcs1 c 254 1194 mknod /dev/hvcs2 c 254 2195 mknod /dev/hvcs3 c 254 3196 197Using mknod to manually create the device entries makes these device nodes198persistent. Once created they will exist prior to the driver insmod.199 200Attempting to connect an application to /dev/hvcs* prior to insertion of201the hvcs module will result in an error message similar to the following::202 203 "/dev/hvcs*: No such device".204 205NOTE: Just because there is a device node present doesn't mean that there206is a vty-server device configured for that node.207 2085. Connection209=============210 211Since this driver controls devices that provide a tty interface a user can212interact with the device node entries using any standard tty-interactive213method (e.g. "cat", "dd", "echo"). The intent of this driver however, is214to provide real time console interaction with a Linux partition's console,215which requires the use of applications that provide bi-directional,216interactive I/O with a tty device.217 218Applications (e.g. "minicom" and "screen") that act as terminal emulators219or perform terminal type control sequence conversion on the data being220passed through them are NOT acceptable for providing interactive console221I/O. These programs often emulate antiquated terminal types (vt100 and222ANSI) and expect inbound data to take the form of one of these supported223terminal types but they either do not convert, or do not _adequately_224convert, outbound data into the terminal type of the terminal which invoked225them (though screen makes an attempt and can apparently be configured with226much termcap wrestling.)227 228For this reason kermit and cu are two of the recommended applications for229interacting with a Linux console via an hvcs device. These programs simply230act as a conduit for data transfer to and from the tty device. They do not231require inbound data to take the form of a particular terminal type, nor do232they cook outbound data to a particular terminal type.233 234In order to ensure proper functioning of console applications one must make235sure that once connected to a /dev/hvcs console that the console's $TERM236env variable is set to the exact terminal type of the terminal emulator237used to launch the interactive I/O application. If one is using xterm and238kermit to connect to /dev/hvcs0 when the console prompt becomes available239one should "export TERM=xterm" on the console. This tells ncurses240applications that are invoked from the console that they should output241control sequences that xterm can understand.242 243As a precautionary measure an hvcs user should always "exit" from their244session before disconnecting an application such as kermit from the device245node. If this is not done, the next user to connect to the console will246continue using the previous user's logged in session which includes247using the $TERM variable that the previous user supplied.248 249Hotplug add and remove of vty-server adapters affects which /dev/hvcs* node250is used to connect to each vty-server adapter. In order to determine which251vty-server adapter is associated with which /dev/hvcs* node a special sysfs252attribute has been added to each vty-server sysfs entry. This entry is253called "index" and showing it reveals an integer that refers to the254/dev/hvcs* entry to use to connect to that device. For instance cating the255index attribute of vty-server adapter 30000004 shows the following::256 257 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index258 2259 260This index of '2' means that in order to connect to vty-server adapter26130000004 the user should interact with /dev/hvcs2.262 263It should be noted that due to the system hotplug I/O capabilities of a264system the /dev/hvcs* entry that interacts with a particular vty-server265adapter is not guaranteed to remain the same across system reboots. Look266in the Q & A section for more on this issue.267 2686. Disconnection269================270 271As a security feature to prevent the delivery of stale data to an272unintended target the Power5 system firmware disables the fetching of data273and discards that data when a connection between a vty-server and a vty has274been severed. As an example, when a vty-server is immediately disconnected275from a vty following output of data to the vty the vty adapter may not have276enough time between when it received the data interrupt and when the277connection was severed to fetch the data from firmware before the fetch is278disabled by firmware.279 280When hvcs is being used to serve consoles this behavior is not a huge issue281because the adapter stays connected for large amounts of time following282almost all data writes. When hvcs is being used as a tty conduit to tunnel283data between two partitions [see Q & A below] this is a huge problem284because the standard Linux behavior when cat'ing or dd'ing data to a device285is to open the tty, send the data, and then close the tty. If this driver286manually terminated vty-server connections on tty close this would close287the vty-server and vty connection before the target vty has had a chance to288fetch the data.289 290Additionally, disconnecting a vty-server and vty only on module removal or291adapter removal is impractical because other vty-servers in other292partitions may require the usage of the target vty at any time.293 294Due to this behavioral restriction disconnection of vty-servers from the295connected vty is a manual procedure using a write to a sysfs attribute296outlined below, on the other hand the initial vty-server connection to a297vty is established automatically by this driver. Manual vty-server298connection is never required.299 300In order to terminate the connection between a vty-server and vty the301"vterm_state" sysfs attribute within each vty-server's sysfs entry is used.302Reading this attribute reveals the current connection state of the303vty-server adapter. A zero means that the vty-server is not connected to a304vty. A one indicates that a connection is active.305 306Writing a '0' (zero) to the vterm_state attribute will disconnect the VTERM307connection between the vty-server and target vty ONLY if the vterm_state308previously read '1'. The write directive is ignored if the vterm_state309read '0' or if any value other than '0' was written to the vterm_state310attribute. The following example will show the method used for verifying311the vty-server connection status and disconnecting a vty-server connection::312 313 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state314 1315 316 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state317 318 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state319 0320 321All vty-server connections are automatically terminated when the device is322hotplug removed and when the module is removed.323 3247. Configuration325================326 327Each vty-server has a sysfs entry in the /sys/devices/vio directory, which328is symlinked in several other sysfs tree directories, notably under the329hvcs driver entry, which looks like the following example::330 331 Pow5:/sys/bus/vio/drivers/hvcs # ls332 . .. 30000003 30000004 rescan333 334By design, firmware notifies the hvcs driver of vty-server lifetimes and335partner vty removals but not the addition of partner vtys. Since an HMC336Super Admin can add partner info dynamically we have provided the hvcs337driver sysfs directory with the "rescan" update attribute which will query338firmware and update the partner info for all the vty-servers that this339driver manages. Writing a '1' to the attribute triggers the update. An340explicit example follows:341 342 Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan343 344Reading the attribute will indicate a state of '1' or '0'. A one indicates345that an update is in process. A zero indicates that an update has346completed or was never executed.347 348Vty-server entries in this directory are a 32 bit partition unique unit349address that is created by firmware. An example vty-server sysfs entry350looks like the following::351 352 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls353 . current_vty devspec name partner_vtys354 .. index partner_clcs vterm_state355 356Each entry is provided, by default with a "name" attribute. Reading the357"name" attribute will reveal the device type as shown in the following358example::359 360 Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name361 vty-server362 363Each entry is also provided, by default, with a "devspec" attribute which364reveals the full device specification when read, as shown in the following365example::366 367 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec368 /vdevice/vty-server@30000004369 370Each vty-server sysfs dir is provided with two read-only attributes that371provide lists of easily parsed partner vty data: "partner_vtys" and372"partner_clcs"::373 374 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys375 30000000376 30000001377 30000002378 30000000379 30000000380 381 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcs382 U5112.428.103048A-V3-C0383 U5112.428.103048A-V3-C2384 U5112.428.103048A-V3-C3385 U5112.428.103048A-V4-C0386 U5112.428.103048A-V5-C0387 388Reading partner_vtys returns a list of partner vtys. Vty unit address389numbering is only per-partition-unique so entries will frequently repeat.390 391Reading partner_clcs returns a list of "converged location codes" which are392composed of a system serial number followed by "-V*", where the '*' is the393target partition number, and "-C*", where the '*' is the slot of the394adapter. The first vty partner corresponds to the first clc item, the395second vty partner to the second clc item, etc.396 397A vty-server can only be connected to a single vty at a time. The entry,398"current_vty" prints the clc of the currently selected partner vty when399read.400 401The current_vty can be changed by writing a valid partner clc to the entry402as in the following example::403 404 Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304405 8A-V4-C0 > current_vty406 407Changing the current_vty when a vty-server is already connected to a vty408does not affect the current connection. The change takes effect when the409currently open connection is freed.410 411Information on the "vterm_state" attribute was covered earlier on the412chapter entitled "disconnection".413 4148. Questions & Answers:415=======================416 417Q: What are the security concerns involving hvcs?418 419A: There are three main security concerns:420 421 1. The creator of the /dev/hvcs* nodes has the ability to restrict422 the access of the device entries to certain users or groups. It423 may be best to create a special hvcs group privilege for providing424 access to system consoles.425 426 2. To provide network security when grabbing the console it is427 suggested that the user connect to the console hosting partition428 using a secure method, such as SSH or sit at a hardware console.429 430 3. Make sure to exit the user session when done with a console or431 the next vty-server connection (which may be from another432 partition) will experience the previously logged in session.433 434---------------------------------------------------------------------------435 436Q: How do I multiplex a console that I grab through hvcs so that other437people can see it:438 439A: You can use "screen" to directly connect to the /dev/hvcs* device and440setup a session on your machine with the console group privileges. As441pointed out earlier by default screen doesn't provide the termcap settings442for most terminal emulators to provide adequate character conversion from443term type "screen" to others. This means that curses based programs may444not display properly in screen sessions.445 446---------------------------------------------------------------------------447 448Q: Why are the colors all messed up?449Q: Why are the control characters acting strange or not working?450Q: Why is the console output all strange and unintelligible?451 452A: Please see the preceding section on "Connection" for a discussion of how453applications can affect the display of character control sequences.454Additionally, just because you logged into the console using and xterm455doesn't mean someone else didn't log into the console with the HMC console456(vt320) before you and leave the session logged in. The best thing to do457is to export TERM to the terminal type of your terminal emulator when you458get the console. Additionally make sure to "exit" the console before you459disconnect from the console. This will ensure that the next user gets460their own TERM type set when they login.461 462---------------------------------------------------------------------------463 464Q: When I try to CONNECT kermit to an hvcs device I get:465"Sorry, can't open connection: /dev/hvcs*"What is happening?466 467A: Some other Power5 console mechanism has a connection to the vty and468isn't giving it up. You can try to force disconnect the consoles from the469HMC by right clicking on the partition and then selecting "close terminal".470Otherwise you have to hunt down the people who have console authority. It471is possible that you already have the console open using another kermit472session and just forgot about it. Please review the console options for473Power5 systems to determine the many ways a system console can be held.474 475OR476 477A: Another user may not have a connectivity method currently attached to a478/dev/hvcs device but the vterm_state may reveal that they still have the479vty-server connection established. They need to free this using the method480outlined in the section on "Disconnection" in order for others to connect481to the target vty.482 483OR484 485A: The user profile you are using to execute kermit probably doesn't have486permissions to use the /dev/hvcs* device.487 488OR489 490A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*491entry still exists (on systems without udev).492 493OR494 495A: There is not a corresponding vty-server device that maps to an existing496/dev/hvcs* entry.497 498---------------------------------------------------------------------------499 500Q: When I try to CONNECT kermit to an hvcs device I get:501"Sorry, write access to UUCP lockfile directory denied."502 503A: The /dev/hvcs* entry you have specified doesn't exist where you said it504does? Maybe you haven't inserted the module (on systems with udev).505 506---------------------------------------------------------------------------507 508Q: If I already have one Linux partition installed can I use hvcs on said509partition to provide the console for the install of a second Linux510partition?511 512A: Yes granted that your are connected to the /dev/hvcs* device using513kermit or cu or some other program that doesn't provide terminal emulation.514 515---------------------------------------------------------------------------516 517Q: Can I connect to more than one partition's console at a time using this518driver?519 520A: Yes. Of course this means that there must be more than one vty-server521configured for this partition and each must point to a disconnected vty.522 523---------------------------------------------------------------------------524 525Q: Does the hvcs driver support dynamic (hotplug) addition of devices?526 527A: Yes, if you have dlpar and hotplug enabled for your system and it has528been built into the kernel the hvcs drivers is configured to dynamically529handle additions of new devices and removals of unused devices.530 531---------------------------------------------------------------------------532 533Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter534after a reboot. What happened?535 536A: Assignment of vty-server adapters to /dev/hvcs* entries is always done537in the order that the adapters are exposed. Due to hotplug capabilities of538this driver assignment of hotplug added vty-servers may be in a different539order than how they would be exposed on module load. Rebooting or540reloading the module after dynamic addition may result in the /dev/hvcs*541and vty-server coupling changing if a vty-server adapter was added in a542slot between two other vty-server adapters. Refer to the section above543on how to determine which vty-server goes with which /dev/hvcs* node.544Hint; look at the sysfs "index" attribute for the vty-server.545 546---------------------------------------------------------------------------547 548Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty549device on that partition as the other end of the pipe?550 551A: Yes, on Power5 platforms the hvc_console driver provides a tty interface552for extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).553In order to get a tty conduit working between the two partitions the HMC554Super Admin must create an additional "serial server" for the target555partition with the HMC gui which will show up as /dev/hvc* when the target556partition is rebooted.557 558The HMC Super Admin then creates an additional "serial client" for the559current partition and points this at the target partition's newly created560"serial server" adapter (remember the slot). This shows up as an561additional /dev/hvcs* device.562 563Now a program on the target system can be configured to read or write to564/dev/hvc* and another program on the current partition can be configured to565read or write to /dev/hvcs*. Now you have a tty conduit between two566partitions.567 568---------------------------------------------------------------------------569 5709. Reporting Bugs:571==================572 573The proper channel for reporting bugs is either through the Linux OS574distribution company that provided your OS or by posting issues to the575PowerPC development mailing list at:576 577linuxppc-dev@lists.ozlabs.org578 579This request is to provide a documented and searchable public exchange580of the problems and solutions surrounding this driver for the benefit of581all users.582