Put in remaining pages and wiki contents.
[ikiwiki.git] / docs / handbook / handbook-linuxemu-lbc-install.mdwn
1 \r
2 \r
3 ## 22.2 Installation \r
4 \r
5 Linux binary compatibility is not turned on by default. The easiest way to enable this functionality is to load the `linux` KLD object (***Kernel Loadable Device***). You can load this module by simply typing `linux` at the command prompt.\r
6 \r
7 If you would like Linux compatibility to always be enabled, then you should add the following line to `/etc/rc.conf`:\r
8 \r
9     \r
10     linux_enable="YES"\r
11 \r
12 \r
13 The [kldstat(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#kldstat&section8) command can be used to verify that the KLD is loaded:\r
14 \r
15     \r
16     % kldstat\r
17     Id Refs Address    Size     Name\r
18      1    2 0xc0100000 16bdb8   kernel\r
19      7    1 0xc24db000 d000     linux.ko\r
20 \r
21 \r
22 If for some reason you do not want to or cannot load the KLD, then you may statically link Linux binary compatibility into the kernel by adding `options COMPAT_LINUX` to your kernel configuration file. Then install your new kernel as described in [kernelconfig.html Chapter 9].\r
23 \r
24 ### 22.2.1 Installing Linux Runtime Libraries \r
25 \r
26 This can be done one of two ways, either by using the [linuxemu-lbc-install.html#LINUXEMU-SUSE-PKGSRC suse] package, or by installing them [linuxemu-lbc-install.html#LINUXEMU-LIBS-MANUALLY manually].\r
27 \r
28 #### Installing Using suse Package \r
29 \r
30 This is by far the easiest method to use when installing the runtime libraries. It is just like installing any other package from the [pkgsrc collection](file://localhost/usr/pkgsrc/). Simply do the following:\r
31 \r
32     \r
33     # cd /usr/pkgsrc/meta-pkgs/suse9\r
34     # make install distclean\r
35     # ln -s /usr/pkg/emul /compat\r
36 \r
37 \r
38 You should now have working Linux binary compatibility. Some programs may complain about incorrect minor versions of the system libraries. In general, however, this does not seem to be a problem.\r
39 \r
40  **Note:** There may be multiple versions of the [`meta-pkgs/suse`](http://pkgsrc.se/meta-pkgs/suse) package available, corresponding to different versions of various Linux distributions. You should install the package most closely resembling the requirements of the Linux applications you would like to install.\r
41 \r
42 #### Installing Libraries Manually \r
43 \r
44 If you do not have the ***pkgsrc*** collection installed, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a ***shadow root*** directory, `/compat/linux`, for Linux libraries on your DragonFly system. Any shared libraries opened by Linux programs run under DragonFly will look in this tree first. So, if a Linux program loads, for example, `/lib/libc.so`, DragonFly will first try to open `/compat/linux/lib/libc.so`, and if that does not exist, it will then try `/lib/libc.so`. Shared libraries should be installed in the shadow tree `/compat/linux/lib` rather than the paths that the Linux `ld.so` reports.\r
45 \r
46 Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your DragonFly system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work.\r
47 \r
48 #### How to Install Additional Shared Libraries \r
49 \r
50 What if you install the `suse` package and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions you will need to be `root` on your DragonFly system).\r
51 \r
52 If you have access to a Linux system, see what shared libraries the application needs, and copy them to your DragonFly system. Look at the following example:\r
53 \r
54 Let us assume you used FTP to get the Linux binary of  **Doom** , and put it on a Linux system you have access to. You then can check which shared libraries it needs by running `ldd linuxdoom`, like so:\r
55 \r
56     \r
57     % ldd linuxdoom\r
58     libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0\r
59     libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0\r
60     libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29\r
61 \r
62 \r
63 You would need to get all the files from the last column, and put them under `/compat/linux`, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your DragonFly system:\r
64 \r
65     \r
66     /compat/linux/usr/X11/lib/libXt.so.3.1.0\r
67     /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0\r
68     /compat/linux/usr/X11/lib/libX11.so.3.1.0\r
69     /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0\r
70     /compat/linux/lib/libc.so.4.6.29\r
71     /compat/linux/lib/libc.so.4 -> libc.so.4.6.29\r
72 \r
73 \r
74  **Note:** Note that if you already have a Linux shared library with a matching major revision number to the first column of the `ldd` output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system:\r
75 \r
76     \r
77     /compat/linux/lib/libc.so.4.6.27\r
78     /compat/linux/lib/libc.so.4 -> libc.so.4.6.27\r
79 \r
80 \r
81 and you find a new binary that claims to require a later version according to the output of `ldd`:\r
82 \r
83     \r
84     libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29\r
85 \r
86 \r
87 If it is only one or two versions out of date in the in the trailing digit then do not worry about copying `/lib/libc.so.4.6.29` too, because the program should work fine with the slightly older version. However, if you like, you can decide to replace the `libc.so` anyway, and that should leave you with:\r
88 \r
89     \r
90     /compat/linux/lib/libc.so.4.6.29\r
91     /compat/linux/lib/libc.so.4 -> libc.so.4.6.29\r
92 \r
93 \r
94  **Note:** The symbolic link mechanism is ***only*** needed for Linux binaries. The DragonFly runtime linker takes care of looking for matching major revision numbers itself and you do not need to worry about it.\r
95 \r
96 ### 22.2.2 Installing Linux ELF Binaries \r
97 \r
98 ELF binaries sometimes require an extra step of ***branding***. If you attempt to run an unbranded ELF binary, you will get an error message like the following:\r
99 \r
100     \r
101     % ./my-linux-elf-binary\r
102     ELF binary type not known\r
103     Abort\r
104 \r
105 \r
106 To help the DragonFly kernel distinguish between a DragonFly ELF binary from a Linux binary, use the [brandelf(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#brandelf&section1) utility.\r
107 \r
108     \r
109     % brandelf -t Linux my-linux-elf-binary\r
110 \r
111 \r
112 The GNU toolchain now places the appropriate branding information into ELF binaries automatically, so this step should only be needed for older, libc5 binaries.\r
113 \r
114 ### 22.2.3 Configuring the Hostname Resolver \r
115 \r
116 If DNS does not work or you get this message:\r
117 \r
118     \r
119     resolv+: "bind" is an invalid keyword resolv+:\r
120     "hosts" is an invalid keyword\r
121 \r
122 \r
123 You will need to configure a `/compat/linux/etc/host.conf` file containing:\r
124 \r
125     \r
126     order hosts, bind\r
127     multi on\r
128 \r
129 \r
130 The order here specifies that `/etc/hosts` is searched first and DNS is searched second. When `/compat/linux/etc/host.conf` is not installed, Linux applications find DragonFly's `/etc/host.conf` and complain about the incompatible DragonFly syntax. You should remove `bind` if you have not configured a name server using the `/etc/resolv.conf` file.\r
131 \r
132 \r
133 \r
134 CategoryHandbook\r
135 CategoryHandbook-linuxcompatibility\r