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