+#: ../src/guestfs.pod:976
+msgid "If that named device exists, use it. If not, continue."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:980
+msgid "Replace initial C</dev/sd> string with C</dev/vd>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:982
+msgid "If that named device exists, use it. If not, return an error."
+msgstr ""
+
+# type: =head3
+#: ../src/guestfs.pod:986
+msgid "PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:988
+msgid ""
+"Although the standard naming scheme and automatic translation is useful for "
+"simple programs and guestfish scripts, for larger programs it is best not to "
+"rely on this mechanism."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:992
+msgid ""
+"Where possible for maximum future portability programs using libguestfs "
+"should use these future-proof techniques:"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:999
+msgid ""
+"Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list actual "
+"device names, and then use those names directly."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1002
+msgid ""
+"Since those device names exist by definition, they will never be translated."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1007
+msgid ""
+"Use higher level ways to identify filesystems, such as LVM names, UUIDs and "
+"filesystem labels."
+msgstr ""
+
+# type: =head1
+#: ../src/guestfs.pod:1012
+msgid "SECURITY"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1014
+msgid ""
+"This section discusses security implications of using libguestfs, "
+"particularly with untrusted or malicious guests or disk images."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1017
+msgid "GENERAL SECURITY CONSIDERATIONS"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1019
+msgid ""
+"Be careful with any files or data that you download from a guest (by "
+"\"download\" we mean not just the L</guestfs_download> command but any "
+"command that reads files, filenames, directories or anything else from a "
+"disk image). An attacker could manipulate the data to fool your program "
+"into doing the wrong thing. Consider cases such as:"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1029
+msgid "the data (file etc) not being present"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1033
+msgid "being present but empty"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1037
+msgid "being much larger than normal"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1041
+msgid "containing arbitrary 8 bit data"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1045
+msgid "being in an unexpected character encoding"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1049
+msgid "containing homoglyphs."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1053
+msgid "SECURITY OF MOUNTING FILESYSTEMS"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1055
+msgid ""
+"When you mount a filesystem under Linux, mistakes in the kernel filesystem "
+"(VFS) module can sometimes be escalated into exploits by deliberately "
+"creating a malicious, malformed filesystem. These exploits are very severe "
+"for two reasons. Firstly there are very many filesystem drivers in the "
+"kernel, and many of them are infrequently used and not much developer "
+"attention has been paid to the code. Linux userspace helps potential "
+"crackers by detecting the filesystem type and automatically choosing the "
+"right VFS driver, even if that filesystem type is obscure or unexpected for "
+"the administrator. Secondly, a kernel-level exploit is like a local root "
+"exploit (worse in some ways), giving immediate and total access to the "
+"system right down to the hardware level."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1068
+msgid ""
+"That explains why you should never mount a filesystem from an untrusted "
+"guest on your host kernel. How about libguestfs? We run a Linux kernel "
+"inside a qemu virtual machine, usually running as a non-root user. The "
+"attacker would need to write a filesystem which first exploited the kernel, "
+"and then exploited either qemu virtualization (eg. a faulty qemu driver) or "
+"the libguestfs protocol, and finally to be as serious as the host kernel "
+"exploit it would need to escalate its privileges to root. This multi-step "
+"escalation, performed by a static piece of data, is thought to be extremely "
+"hard to do, although we never say 'never' about security issues."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1079
+msgid ""
+"In any case callers can reduce the attack surface by forcing the filesystem "
+"type when mounting (use L</guestfs_mount_vfs>)."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1082
+msgid "PROTOCOL SECURITY"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1084
+msgid ""
+"The protocol is designed to be secure, being based on RFC 4506 (XDR) with a "
+"defined upper message size. However a program that uses libguestfs must "
+"also take care - for example you can write a program that downloads a binary "
+"from a disk image and executes it locally, and no amount of protocol "
+"security will save you from the consequences."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1090
+msgid "INSPECTION SECURITY"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1092
+msgid ""
+"Parts of the inspection API (see L</INSPECTION>) return untrusted strings "
+"directly from the guest, and these could contain any 8 bit data. Callers "
+"should be careful to escape these before printing them to a structured file "
+"(for example, use HTML escaping if creating a web page)."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1098
+msgid ""
+"The inspection API parses guest configuration using two external libraries: "
+"Augeas (Linux configuration) and hivex (Windows Registry). Both are "
+"designed to be robust in the face of malicious data, although denial of "
+"service attacks are still possible, for example with oversized configuration "
+"files."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1104
+msgid "RUNNING UNTRUSTED GUEST COMMANDS"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1106
+msgid ""
+"Be very cautious about running commands from the guest. By running a "
+"command in the guest, you are giving CPU time to a binary that you do not "
+"control, under the same user account as the library, albeit wrapped in qemu "
+"virtualization. More information and alternatives can be found in the "
+"section L</RUNNING COMMANDS>."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1112
+msgid "CVE-2010-3851"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1114
+msgid "https://bugzilla.redhat.com/642934"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1116
+msgid ""
+"This security bug concerns the automatic disk format detection that qemu "
+"does on disk images."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1119
+msgid ""
+"A raw disk image is just the raw bytes, there is no header. Other disk "
+"images like qcow2 contain a special header. Qemu deals with this by looking "
+"for one of the known headers, and if none is found then assuming the disk "
+"image must be raw."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1124
+msgid ""
+"This allows a guest which has been given a raw disk image to write some "
+"other header. At next boot (or when the disk image is accessed by "
+"libguestfs) qemu would do autodetection and think the disk image format was, "
+"say, qcow2 based on the header written by the guest."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1129
+msgid ""
+"This in itself would not be a problem, but qcow2 offers many features, one "
+"of which is to allow a disk image to refer to another image (called the "
+"\"backing disk\"). It does this by placing the path to the backing disk "
+"into the qcow2 header. This path is not validated and could point to any "
+"host file (eg. \"/etc/passwd\"). The backing disk is then exposed through "
+"\"holes\" in the qcow2 disk image, which of course is completely under the "
+"control of the attacker."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1137
+msgid ""
+"In libguestfs this is rather hard to exploit except under two circumstances:"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1144
+msgid "You have enabled the network or have opened the disk in write mode."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1148
+msgid ""
+"You are also running untrusted code from the guest (see L</RUNNING "
+"COMMANDS>)."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1153
+msgid ""
+"The way to avoid this is to specify the expected disk format when adding "
+"disks (the optional C<format> option to L</guestfs_add_drive_opts>). You "
+"should always do this if the disk is raw format, and it's a good idea for "
+"other cases too."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1158
+msgid ""
+"For disks added from libvirt using calls like L</guestfs_add_domain>, the "
+"format is fetched from libvirt and passed through."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1161
+msgid ""
+"For libguestfs tools, use the I<--format> command line parameter as "
+"appropriate."
+msgstr ""
+
+# type: =head1
+#: ../src/guestfs.pod:1164
+msgid "CONNECTION MANAGEMENT"
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1166
+msgid "guestfs_h *"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1168
+msgid ""
+"C<guestfs_h> is the opaque type representing a connection handle. Create a "
+"handle by calling L</guestfs_create>. Call L</guestfs_close> to free the "
+"handle and release all resources used."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1172
+msgid ""
+"For information on using multiple handles and threads, see the section L</"
+"MULTIPLE HANDLES AND MULTIPLE THREADS> below."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1175
+msgid "guestfs_create"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1177
+#, no-wrap
+msgid ""
+" guestfs_h *guestfs_create (void);\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1179
+msgid "Create a connection handle."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1181
+msgid ""
+"You have to call L</guestfs_add_drive_opts> (or one of the equivalent calls) "
+"on the handle at least once."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1184
+msgid ""
+"This function returns a non-NULL pointer to a handle on success or NULL on "
+"error."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1187
+msgid "After configuring the handle, you have to call L</guestfs_launch>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1189
+msgid ""
+"You may also want to configure error handling for the handle. See L</ERROR "
+"HANDLING> section below."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1192
+msgid "guestfs_close"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1194
+#, no-wrap
+msgid ""
+" void guestfs_close (guestfs_h *g);\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1196
+msgid "This closes the connection handle and frees up all resources used."
+msgstr ""
+
+# type: =head1
+#: ../src/guestfs.pod:1198
+msgid "ERROR HANDLING"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1200
+msgid ""
+"API functions can return errors. For example, almost all functions that "
+"return C<int> will return C<-1> to indicate an error."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1203
+msgid ""
+"Additional information is available for errors: an error message string and "
+"optionally an error number (errno) if the thing that failed was a system "
+"call."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1207
+msgid ""
+"You can get at the additional information about the last error on the handle "
+"by calling L</guestfs_last_error>, L</guestfs_last_errno>, and/or by setting "
+"up an error handler with L</guestfs_set_error_handler>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1212
+msgid ""
+"When the handle is created, a default error handler is installed which "
+"prints the error message string to C<stderr>. For small short-running "
+"command line programs it is sufficient to do:"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1216
+#, no-wrap
+msgid ""
+" if (guestfs_launch (g) == -1)\n"
+" exit (EXIT_FAILURE);\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1219
+msgid ""
+"since the default error handler will ensure that an error message has been "
+"printed to C<stderr> before the program exits."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1222
+msgid ""
+"For other programs the caller will almost certainly want to install an "
+"alternate error handler or do error handling in-line like this:"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1225
+#, no-wrap
+msgid ""
+" g = guestfs_create ();\n"
+" \n"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1227
+#, no-wrap
+msgid ""
+" /* This disables the default behaviour of printing errors\n"
+" on stderr. */\n"
+" guestfs_set_error_handler (g, NULL, NULL);\n"
+" \n"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1231
+#, no-wrap
+msgid ""
+" if (guestfs_launch (g) == -1) {\n"
+" /* Examine the error message and print it etc. */\n"
+" char *msg = guestfs_last_error (g);\n"
+" int errnum = guestfs_last_errno (g);\n"
+" fprintf (stderr, \"%s\\n\", msg);\n"
+" /* ... */\n"
+" }\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1239
+msgid ""
+"Out of memory errors are handled differently. The default action is to call "
+"L<abort(3)>. If this is undesirable, then you can set a handler using L</"
+"guestfs_set_out_of_memory_handler>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1243
+msgid ""
+"L</guestfs_create> returns C<NULL> if the handle cannot be created, and "
+"because there is no handle if this happens there is no way to get additional "
+"error information. However L</guestfs_create> is supposed to be a "
+"lightweight operation which can only fail because of insufficient memory (it "
+"returns NULL in this case)."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1249
+msgid "guestfs_last_error"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1251
+#, no-wrap
+msgid ""
+" const char *guestfs_last_error (guestfs_h *g);\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1253
+msgid ""
+"This returns the last error message that happened on C<g>. If there has not "
+"been an error since the handle was created, then this returns C<NULL>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1257
+msgid ""
+"The lifetime of the returned string is until the next error occurs, or L</"
+"guestfs_close> is called."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1260
+msgid "guestfs_last_errno"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1262
+#, no-wrap
+msgid ""
+" int guestfs_last_errno (guestfs_h *g);\n"
+"\n"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1264
+msgid "This returns the last error number (errno) that happened on C<g>."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1266
+msgid "If successful, an errno integer not equal to zero is returned."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1268
+msgid ""
+"If no error, this returns 0. This call can return 0 in three situations:"
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1275
+msgid "There has not been any error on the handle."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1279
+msgid ""
+"There has been an error but the errno was meaningless. This corresponds to "
+"the case where the error did not come from a failed system call, but for "
+"some other reason."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1285
+msgid ""
+"There was an error from a failed system call, but for some reason the errno "
+"was not captured and returned. This usually indicates a bug in libguestfs."
+msgstr ""
+
+# type: textblock
+#: ../src/guestfs.pod:1291
+msgid ""
+"Libguestfs tries to convert the errno from inside the applicance into a "
+"corresponding errno for the caller (not entirely trivial: the appliance "
+"might be running a completely different operating system from the library "
+"and error numbers are not standardized across Un*xen). If this could not be "
+"done, then the error is translated to C<EINVAL>. In practice this should "
+"only happen in very rare circumstances."
+msgstr ""
+
+# type: =head2
+#: ../src/guestfs.pod:1299
+msgid "guestfs_set_error_handler"
+msgstr ""
+
+# type: verbatim
+#: ../src/guestfs.pod:1301
+#, no-wrap
git.annexia.org / libguestfs.git / blobdiff