# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR Red Hat Inc.
# This file is distributed under the same license as the libguestfs package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: libguestfs 1.7.16\n"
"Report-Msgid-Bugs-To: libguestfs@redhat.com\n"
"POT-Creation-Date: 2010-11-26 22:32+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: ENCODING"
# type: =encoding
#: ../src/guestfs.pod:1 ../fish/guestfish.pod:1 ../test-tool/libguestfs-test-tool.pod:1 ../fuse/guestmount.pod:1 ../tools/virt-edit.pl:30 ../tools/virt-win-reg.pl:33 ../tools/virt-resize.pl:38 ../tools/virt-list-filesystems.pl:28 ../tools/virt-tar.pl:29 ../tools/virt-make-fs.pl:33 ../tools/virt-list-partitions.pl:28
msgid "utf8"
msgstr ""
# type: =head1
#: ../src/guestfs.pod:3 ../fish/guestfish.pod:3 ../test-tool/libguestfs-test-tool.pod:3 ../fuse/guestmount.pod:3 ../tools/virt-edit.pl:32 ../tools/virt-win-reg.pl:35 ../tools/virt-resize.pl:40 ../tools/virt-list-filesystems.pl:30 ../tools/virt-tar.pl:31 ../tools/virt-make-fs.pl:35 ../tools/virt-list-partitions.pl:30
msgid "NAME"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:5
msgid "guestfs - Library for accessing and modifying virtual machine images"
msgstr ""
# type: =head1
#: ../src/guestfs.pod:7 ../fish/guestfish.pod:7 ../test-tool/libguestfs-test-tool.pod:7 ../fuse/guestmount.pod:7 ../tools/virt-edit.pl:36 ../tools/virt-win-reg.pl:39 ../tools/virt-resize.pl:44 ../tools/virt-list-filesystems.pl:34 ../tools/virt-tar.pl:35 ../tools/virt-make-fs.pl:39 ../tools/virt-list-partitions.pl:34
msgid "SYNOPSIS"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:9
#, no-wrap
msgid ""
" #include <guestfs.h>\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:11
#, no-wrap
msgid ""
" guestfs_h *g = guestfs_create ();\n"
" guestfs_add_drive (g, \"guest.img\");\n"
" guestfs_launch (g);\n"
" guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
" guestfs_touch (g, \"/hello\");\n"
" guestfs_umount (g, \"/\");\n"
" guestfs_sync (g);\n"
" guestfs_close (g);\n"
"\n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:20
#, no-wrap
msgid ""
" cc prog.c -o prog -lguestfs\n"
"or:\n"
" cc prog.c -o prog `pkg-config libguestfs --cflags --libs`\n"
"\n"
msgstr ""
# type: =head1
#: ../src/guestfs.pod:24 ../fish/guestfish.pod:30 ../test-tool/libguestfs-test-tool.pod:11 ../fuse/guestmount.pod:20 ../tools/virt-edit.pl:50 ../tools/virt-win-reg.pl:63 ../tools/virt-resize.pl:50 ../tools/virt-list-filesystems.pl:40 ../tools/virt-tar.pl:72 ../tools/virt-make-fs.pl:47 ../tools/virt-list-partitions.pl:40
msgid "DESCRIPTION"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:26
msgid ""
"Libguestfs is a library for accessing and modifying guest disk images. "
"Amongst the things this is good for: making batch configuration changes to "
"guests, getting disk used/free statistics (see also: virt-df), migrating "
"between virtualization systems (see also: virt-p2v), performing partial "
"backups, performing partial guest clones, cloning guests and changing "
"registry/UUID/hostname info, and much else besides."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:34
msgid ""
"Libguestfs uses Linux kernel and qemu code, and can access any type of guest "
"filesystem that Linux and qemu can, including but not limited to: ext2/3/4, "
"btrfs, FAT and NTFS, LVM, many different disk partition schemes, qcow, "
"qcow2, vmdk."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:39
msgid ""
"Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, "
"what filesystem is in each LV, etc.). It can also run commands in the "
"context of the guest. Also you can access filesystems over FUSE."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:44
msgid ""
"Libguestfs is a library that can be linked with C and C++ management "
"programs (or management programs written in OCaml, Perl, Python, Ruby, Java, "
"PHP, Haskell or C#). You can also use it from shell scripts or the command "
"line."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:49
msgid ""
"You don't need to be root to use libguestfs, although obviously you do need "
"enough permissions to access the disk images."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:52
msgid ""
"Libguestfs is a large API because it can do many things. For a gentle "
"introduction, please read the L</API OVERVIEW> section next."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:55
msgid ""
"There are also some example programs in the L<guestfs-examples(3)> manual "
"page."
msgstr ""
# type: =head1
#: ../src/guestfs.pod:58
msgid "API OVERVIEW"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:60
msgid ""
"This section provides a gentler overview of the libguestfs API. We also try "
"to group API calls together, where that may not be obvious from reading "
"about the individual calls in the main section of this manual."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:65
msgid "HANDLES"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:67
msgid ""
"Before you can use libguestfs calls, you have to create a handle. Then you "
"must add at least one disk image to the handle, followed by launching the "
"handle, then performing whatever operations you want, and finally closing "
"the handle. By convention we use the single letter C<g> for the name of the "
"handle variable, although of course you can use any name you want."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:74
msgid "The general structure of all libguestfs-using programs looks like this:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:77
#, no-wrap
msgid ""
" guestfs_h *g = guestfs_create ();\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:79
#, no-wrap
msgid ""
" /* Call guestfs_add_drive additional times if there are\n"
" * multiple disk images.\n"
" */\n"
" guestfs_add_drive (g, \"guest.img\");\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:84
#, no-wrap
msgid ""
" /* Most manipulation calls won't work until you've launched\n"
" * the handle 'g'. You have to do this _after_ adding drives\n"
" * and _before_ other commands.\n"
" */\n"
" guestfs_launch (g);\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:90
#, no-wrap
msgid ""
" /* Now you can examine what partitions, LVs etc are available.\n"
" */\n"
" char **partitions = guestfs_list_partitions (g);\n"
" char **logvols = guestfs_lvs (g);\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:95
#, no-wrap
msgid ""
" /* To access a filesystem in the image, you must mount it.\n"
" */\n"
" guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:99
#, no-wrap
msgid ""
" /* Now you can perform filesystem actions on the guest\n"
" * disk image.\n"
" */\n"
" guestfs_touch (g, \"/hello\");\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:104
#, no-wrap
msgid ""
" /* You only need to call guestfs_sync if you have made\n"
" * changes to the guest image. (But if you've made changes\n"
" * then you *must* sync). See also: guestfs_umount and\n"
" * guestfs_umount_all calls.\n"
" */\n"
" guestfs_sync (g);\n"
" \n"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:111
#, no-wrap
msgid ""
" /* Close the handle 'g'. */\n"
" guestfs_close (g);\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:114
msgid ""
"The code above doesn't include any error checking. In real code you should "
"check return values carefully for errors. In general all functions that "
"return integers return C<-1> on error, and all functions that return "
"pointers return C<NULL> on error. See section L</ERROR HANDLING> below for "
"how to handle errors, and consult the documentation for each function call "
"below to see precisely how they return error indications."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:122
msgid "DISK IMAGES"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:124
msgid ""
"The image filename (C<\"guest.img\"> in the example above) could be a disk "
"image from a virtual machine, a L<dd(1)> copy of a physical hard disk, an "
"actual block device, or simply an empty file of zeroes that you have created "
"through L<posix_fallocate(3)>. Libguestfs lets you do useful things to all "
"of these."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:130
msgid ""
"The call you should use in modern code for adding drives is "
"L</guestfs_add_drive_opts>. To add a disk image, allowing writes, and "
"specifying that the format is raw, do:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:134
#, no-wrap
msgid ""
" guestfs_add_drive_opts (g, filename,\n"
" GUESTFS_ADD_DRIVE_OPTS_FORMAT, \"raw\",\n"
" -1);\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:138
msgid "You can add a disk read-only using:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:140
#, no-wrap
msgid ""
" guestfs_add_drive_opts (g, filename,\n"
" GUESTFS_ADD_DRIVE_OPTS_FORMAT, \"raw\",\n"
" GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,\n"
" -1);\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:145
msgid ""
"or by calling the older function L</guestfs_add_drive_ro>. In either case "
"libguestfs won't modify the file."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:148
msgid ""
"Be extremely cautious if the disk image is in use, eg. if it is being used "
"by a virtual machine. Adding it read-write will almost certainly cause disk "
"corruption, but adding it read-only is safe."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:152
msgid ""
"You must add at least one disk image, and you may add multiple disk images. "
"In the API, the disk images are usually referred to as C</dev/sda> (for the "
"first one you added), C</dev/sdb> (for the second one you added), etc."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:157
msgid ""
"Once L</guestfs_launch> has been called you cannot add any more images. You "
"can call L</guestfs_list_devices> to get a list of the device names, in the "
"order that you added them. See also L</BLOCK DEVICE NAMING> below."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:162
msgid "MOUNTING"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:164
msgid ""
"Before you can read or write files, create directories and so on in a disk "
"image that contains filesystems, you have to mount those filesystems using "
"L</guestfs_mount>. If you already know that a disk image contains (for "
"example) one partition with a filesystem on that partition, then you can "
"mount it directly:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:170
#, no-wrap
msgid ""
" guestfs_mount (g, \"/dev/sda1\", \"/\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:172
msgid ""
"where C</dev/sda1> means literally the first partition (C<1>) of the first "
"disk image that we added (C</dev/sda>). If the disk contains Linux LVM2 "
"logical volumes you could refer to those instead (eg. C</dev/VG/LV>)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:176
msgid ""
"If you are given a disk image and you don't know what it contains then you "
"have to find out. Libguestfs can do that too: use "
"L</guestfs_list_partitions> and L</guestfs_lvs> to list possible partitions "
"and LVs, and either try mounting each to see what is mountable, or else "
"examine them with L</guestfs_vfs_type> or L</guestfs_file>. Libguestfs also "
"has a set of APIs for inspection of disk images (see L</INSPECTION> below). "
"But you might find it easier to look at higher level programs built on top "
"of libguestfs, in particular L<virt-inspector(1)>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:186
msgid ""
"To mount a disk image read-only, use L</guestfs_mount_ro>. There are "
"several other variations of the C<guestfs_mount_*> call."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:189
msgid "FILESYSTEM ACCESS AND MODIFICATION"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:191
msgid ""
"The majority of the libguestfs API consists of fairly low-level calls for "
"accessing and modifying the files, directories, symlinks etc on mounted "
"filesystems. There are over a hundred such calls which you can find listed "
"in detail below in this man page, and we don't even pretend to cover them "
"all in this overview."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:197
msgid ""
"Specify filenames as full paths, starting with C<\"/\"> and including the "
"mount point."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:200
msgid ""
"For example, if you mounted a filesystem at C<\"/\"> and you want to read "
"the file called C<\"etc/passwd\"> then you could do:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:203
#, no-wrap
msgid ""
" char *data = guestfs_cat (g, \"/etc/passwd\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:205
msgid ""
"This would return C<data> as a newly allocated buffer containing the full "
"content of that file (with some conditions: see also L</DOWNLOADING> below), "
"or C<NULL> if there was an error."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:209
msgid ""
"As another example, to create a top-level directory on that filesystem "
"called C<\"var\"> you would do:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:212
#, no-wrap
msgid ""
" guestfs_mkdir (g, \"/var\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:214
msgid "To create a symlink you could do:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:216
#, no-wrap
msgid ""
" guestfs_ln_s (g, \"/etc/init.d/portmap\",\n"
" \"/etc/rc3.d/S30portmap\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:219
msgid ""
"Libguestfs will reject attempts to use relative paths and there is no "
"concept of a current working directory."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:222
msgid ""
"Libguestfs can return errors in many situations: for example if the "
"filesystem isn't writable, or if a file or directory that you requested "
"doesn't exist. If you are using the C API (documented here) you have to "
"check for those error conditions after each call. (Other language bindings "
"turn these errors into exceptions)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:228
msgid ""
"File writes are affected by the per-handle umask, set by calling "
"L</guestfs_umask> and defaulting to 022. See L</UMASK>."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:231
msgid "PARTITIONING"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:233
msgid ""
"Libguestfs contains API calls to read, create and modify partition tables on "
"disk images."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:236
msgid ""
"In the common case where you want to create a single partition covering the "
"whole disk, you should use the L</guestfs_part_disk> call:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:240
#, no-wrap
msgid ""
" const char *parttype = \"mbr\";\n"
" if (disk_is_larger_than_2TB)\n"
" parttype = \"gpt\";\n"
" guestfs_part_disk (g, \"/dev/sda\", parttype);\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:245
msgid ""
"Obviously this effectively wipes anything that was on that disk image "
"before."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:248
msgid "LVM2"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:250
msgid ""
"Libguestfs provides access to a large part of the LVM2 API, such as "
"L</guestfs_lvcreate> and L</guestfs_vgremove>. It won't make much sense "
"unless you familiarize yourself with the concepts of physical volumes, "
"volume groups and logical volumes."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:255
msgid ""
"This author strongly recommends reading the LVM HOWTO, online at "
"L<http://tldp.org/HOWTO/LVM-HOWTO/>."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:258
msgid "DOWNLOADING"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:260
msgid ""
"Use L</guestfs_cat> to download small, text only files. This call is "
"limited to files which are less than 2 MB and which cannot contain any ASCII "
"NUL (C<\\0>) characters. However it has a very simple to use API."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:265
msgid ""
"L</guestfs_read_file> can be used to read files which contain arbitrary 8 "
"bit data, since it returns a (pointer, size) pair. However it is still "
"limited to \"small\" files, less than 2 MB."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:269
msgid ""
"L</guestfs_download> can be used to download any file, with no limits on "
"content or size (even files larger than 4 GB)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:272
msgid "To download multiple files, see L</guestfs_tar_out> and L</guestfs_tgz_out>."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:275
msgid "UPLOADING"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:277
msgid ""
"It's often the case that you want to write a file or files to the disk "
"image."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:280
msgid ""
"To write a small file with fixed content, use L</guestfs_write>. To create "
"a file of all zeroes, use L</guestfs_truncate_size> (sparse) or "
"L</guestfs_fallocate64> (with all disk blocks allocated). There are a "
"variety of other functions for creating test files, for example "
"L</guestfs_fill> and L</guestfs_fill_pattern>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:286
msgid ""
"To upload a single file, use L</guestfs_upload>. This call has no limits on "
"file content or size (even files larger than 4 GB)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:289
msgid "To upload multiple files, see L</guestfs_tar_in> and L</guestfs_tgz_in>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:291
msgid ""
"However the fastest way to upload I<large numbers of arbitrary files> is to "
"turn them into a squashfs or CD ISO (see L<mksquashfs(8)> and "
"L<mkisofs(8)>), then attach this using L</guestfs_add_drive_ro>. If you add "
"the drive in a predictable way (eg. adding it last after all other drives) "
"then you can get the device name from L</guestfs_list_devices> and mount it "
"directly using L</guestfs_mount_ro>. Note that squashfs images are "
"sometimes non-portable between kernel versions, and they don't support "
"labels or UUIDs. If you want to pre-build an image or you need to mount it "
"using a label or UUID, use an ISO image instead."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:302
msgid "COPYING"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:304
msgid ""
"There are various different commands for copying between files and devices "
"and in and out of the guest filesystem. These are summarised in the table "
"below."
msgstr ""
# type: =item
#: ../src/guestfs.pod:310
msgid "B<file> to B<file>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:312
msgid ""
"Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy "
"directories recursively."
msgstr ""
# type: =item
#: ../src/guestfs.pod:315
msgid "B<file or device> to B<file or device>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:317
msgid ""
"Use L</guestfs_dd> which efficiently uses L<dd(1)> to copy between files and "
"devices in the guest."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:320
msgid "Example: duplicate the contents of an LV:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:322
#, no-wrap
msgid ""
" guestfs_dd (g, \"/dev/VG/Original\", \"/dev/VG/Copy\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:324
msgid ""
"The destination (C</dev/VG/Copy>) must be at least as large as the source "
"(C</dev/VG/Original>). To copy less than the whole source device, use "
"L</guestfs_copy_size>."
msgstr ""
# type: =item
#: ../src/guestfs.pod:328
msgid "B<file on the host> to B<file or device>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:330
msgid "Use L</guestfs_upload>. See L</UPLOADING> above."
msgstr ""
# type: =item
#: ../src/guestfs.pod:332
msgid "B<file or device> to B<file on the host>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:334
msgid "Use L</guestfs_download>. See L</DOWNLOADING> above."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:338
msgid "LISTING FILES"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:340
msgid ""
"L</guestfs_ll> is just designed for humans to read (mainly when using the "
"L<guestfish(1)>-equivalent command C<ll>)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:343
msgid ""
"L</guestfs_ls> is a quick way to get a list of files in a directory from "
"programs, as a flat list of strings."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:346
msgid ""
"L</guestfs_readdir> is a programmatic way to get a list of files in a "
"directory, plus additional information about each one. It is more "
"equivalent to using the L<readdir(3)> call on a local filesystem."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:350
msgid ""
"L</guestfs_find> and L</guestfs_find0> can be used to recursively list "
"files."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:353
msgid "RUNNING COMMANDS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:355
msgid ""
"Although libguestfs is primarily an API for manipulating files inside guest "
"images, we also provide some limited facilities for running commands inside "
"guests."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:359
msgid "There are many limitations to this:"
msgstr ""
# type: =item
#: ../src/guestfs.pod:363 ../src/guestfs.pod:368 ../src/guestfs.pod:373 ../src/guestfs.pod:377 ../src/guestfs.pod:382 ../src/guestfs.pod:386 ../src/guestfs.pod:391 ../src/guestfs.pod:396 ../src/guestfs.pod:955 ../src/guestfs.pod:959 ../src/guestfs.pod:963 ../src/guestfs.pod:968 ../src/guestfs.pod:976 ../src/guestfs.pod:995 ../src/guestfs.pod:1003 ../src/guestfs.pod:1025 ../src/guestfs.pod:1029 ../src/guestfs.pod:1033 ../src/guestfs.pod:1037 ../src/guestfs.pod:1041 ../src/guestfs.pod:1045 ../src/guestfs.pod:1527 ../src/guestfs.pod:1532 ../src/guestfs.pod:1536 ../src/guestfs.pod:1646 ../src/guestfs.pod:1651 ../src/guestfs.pod:1655 ../src/guestfs.pod:1999 ../src/guestfs.pod:2005 ../src/guestfs.pod:2010 ../src/guestfs.pod:2016 ../src/guestfs.pod:2128 ../src/guestfs.pod:2132 ../src/guestfs.pod:2136 ../src/guestfs.pod:2140 ../src/guestfs-actions.pod:15 ../src/guestfs-actions.pod:22 ../src/guestfs-actions.pod:569 ../src/guestfs-actions.pod:577 ../src/guestfs-actions.pod:584 ../src/guestfs-actions.pod:591 ../src/guestfs-actions.pod:1587 ../src/guestfs-actions.pod:1591 ../src/guestfs-actions.pod:1595 ../src/guestfs-actions.pod:1599 ../src/guestfs-actions.pod:1607 ../src/guestfs-actions.pod:1611 ../src/guestfs-actions.pod:1615 ../src/guestfs-actions.pod:1625 ../src/guestfs-actions.pod:1629 ../src/guestfs-actions.pod:1633 ../src/guestfs-actions.pod:1771 ../src/guestfs-actions.pod:1775 ../src/guestfs-actions.pod:1780 ../src/guestfs-actions.pod:1785 ../src/guestfs-actions.pod:1846 ../src/guestfs-actions.pod:1850 ../src/guestfs-actions.pod:1855 ../fish/guestfish.pod:377 ../fish/guestfish.pod:381 ../fish/guestfish.pod:385 ../fish/guestfish.pod:389 ../fish/guestfish-actions.pod:13 ../fish/guestfish-actions.pod:20 ../fish/guestfish-actions.pod:375 ../fish/guestfish-actions.pod:383 ../fish/guestfish-actions.pod:390 ../fish/guestfish-actions.pod:397 ../fish/guestfish-actions.pod:1067 ../fish/guestfish-actions.pod:1071 ../fish/guestfish-actions.pod:1075 ../fish/guestfish-actions.pod:1079 ../fish/guestfish-actions.pod:1087 ../fish/guestfish-actions.pod:1091 ../fish/guestfish-actions.pod:1095 ../fish/guestfish-actions.pod:1105 ../fish/guestfish-actions.pod:1109 ../fish/guestfish-actions.pod:1113 ../fish/guestfish-actions.pod:1203 ../fish/guestfish-actions.pod:1207 ../fish/guestfish-actions.pod:1212 ../fish/guestfish-actions.pod:1217 ../fish/guestfish-actions.pod:1259 ../fish/guestfish-actions.pod:1263 ../fish/guestfish-actions.pod:1268 ../tools/virt-resize.pl:347 ../tools/virt-resize.pl:352 ../tools/virt-resize.pl:362
msgid "*"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:365
msgid ""
"The kernel version that the command runs under will be different from what "
"it expects."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:370
msgid ""
"If the command needs to communicate with daemons, then most likely they "
"won't be running."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:375
msgid "The command will be running in limited memory."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:379
msgid ""
"The network may not be available unless you enable it (see "
"L</guestfs_set_network>)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:384
msgid "Only supports Linux guests (not Windows, BSD, etc)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:388
msgid "Architecture limitations (eg. won't work for a PPC guest on an X86 host)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:393
msgid ""
"For SELinux guests, you may need to enable SELinux and load policy first. "
"See L</SELINUX> in this manpage."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:398
msgid ""
"I<Security:> It is not safe to run commands from untrusted, possibly "
"malicious guests. These commands may attempt to exploit your program by "
"sending unexpected output. They could also try to exploit the Linux kernel "
"or qemu provided by the libguestfs appliance. They could use the network "
"provided by the libguestfs appliance to bypass ordinary network partitions "
"and firewalls. They could use the elevated privileges or different SELinux "
"context of your program to their advantage."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:407
msgid ""
"A secure alternative is to use libguestfs to install a \"firstboot\" script "
"(a script which runs when the guest next boots normally), and to have this "
"script run the commands you want in the normal context of the running guest, "
"network security and so on. For information about other security issues, "
"see L</SECURITY>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:415
msgid ""
"The two main API calls to run commands are L</guestfs_command> and "
"L</guestfs_sh> (there are also variations)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:418
msgid ""
"The difference is that L</guestfs_sh> runs commands using the shell, so any "
"shell globs, redirections, etc will work."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:421
msgid "CONFIGURATION FILES"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:423
msgid ""
"To read and write configuration files in Linux guest filesystems, we "
"strongly recommend using Augeas. For example, Augeas understands how to "
"read and write, say, a Linux shadow password file or X.org configuration "
"file, and so avoids you having to write that code."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:428
msgid ""
"The main Augeas calls are bound through the C<guestfs_aug_*> APIs. We don't "
"document Augeas itself here because there is excellent documentation on the "
"L<http://augeas.net/> website."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:432
msgid ""
"If you don't want to use Augeas (you fool!) then try calling "
"L</guestfs_read_lines> to get the file as a list of lines which you can "
"iterate over."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:436
msgid "SELINUX"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:438
msgid ""
"We support SELinux guests. To ensure that labeling happens correctly in "
"SELinux guests, you need to enable SELinux and load the guest's policy:"
msgstr ""
# type: =item
#: ../src/guestfs.pod:444 ../src/guestfs.pod:1148 ../src/guestfs.pod:1279
msgid "1."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:446
msgid "Before launching, do:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:448
#, no-wrap
msgid ""
" guestfs_set_selinux (g, 1);\n"
"\n"
msgstr ""
# type: =item
#: ../src/guestfs.pod:450 ../src/guestfs.pod:1152 ../src/guestfs.pod:1283
msgid "2."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:452
msgid ""
"After mounting the guest's filesystem(s), load the policy. This is best "
"done by running the L<load_policy(8)> command in the guest itself:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:456
#, no-wrap
msgid ""
" guestfs_sh (g, \"/usr/sbin/load_policy\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:458
msgid ""
"(Older versions of C<load_policy> require you to specify the name of the "
"policy file)."
msgstr ""
# type: =item
#: ../src/guestfs.pod:461 ../src/guestfs.pod:1289
msgid "3."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:463
msgid ""
"Optionally, set the security context for the API. The correct security "
"context to use can only be known by inspecting the guest. As an example:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:467
#, no-wrap
msgid ""
" guestfs_setcon (g, \"unconfined_u:unconfined_r:unconfined_t:s0\");\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:471
msgid "This will work for running commands and editing existing files."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:473
msgid ""
"When new files are created, you may need to label them explicitly, for "
"example by running the external command C<restorecon pathname>."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:477
msgid "UMASK"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:479
msgid ""
"Certain calls are affected by the current file mode creation mask (the "
"\"umask\"). In particular ones which create files or directories, such as "
"L</guestfs_touch>, L</guestfs_mknod> or L</guestfs_mkdir>. This affects "
"either the default mode that the file is created with or modifies the mode "
"that you supply."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:485
msgid ""
"The default umask is C<022>, so files are created with modes such as C<0644> "
"and directories with C<0755>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:488
msgid ""
"There are two ways to avoid being affected by umask. Either set umask to 0 "
"(call C<guestfs_umask (g, 0)> early after launching). Or call "
"L</guestfs_chmod> after creating each file or directory."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:492
msgid "For more information about umask, see L<umask(2)>."
msgstr ""
# type: =head1
#: ../src/guestfs.pod:494 ../fish/guestfish.pod:670
msgid "ENCRYPTED DISKS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:496
msgid ""
"Libguestfs allows you to access Linux guests which have been encrypted using "
"whole disk encryption that conforms to the Linux Unified Key Setup (LUKS) "
"standard. This includes nearly all whole disk encryption systems used by "
"modern Linux guests."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:502
msgid ""
"Use L</guestfs_vfs_type> to identify LUKS-encrypted block devices (it "
"returns the string C<crypto_LUKS>)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:505
msgid ""
"Then open these devices by calling L</guestfs_luks_open>. Obviously you "
"will require the passphrase!"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:508
msgid ""
"Opening a LUKS device creates a new device mapper device called "
"C</dev/mapper/mapname> (where C<mapname> is the string you supply to "
"L</guestfs_luks_open>). Reads and writes to this mapper device are "
"decrypted from and encrypted to the underlying block device respectively."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:514
msgid ""
"LVM volume groups on the device can be made visible by calling "
"L</guestfs_vgscan> followed by L</guestfs_vg_activate_all>. The logical "
"volume(s) can now be mounted in the usual way."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:518
msgid ""
"Use the reverse process to close a LUKS device. Unmount any logical volumes "
"on it, deactivate the volume groups by caling C<guestfs_vg_activate (g, 0, "
"[\"/dev/VG\"])>. Then close the mapper device by calling "
"L</guestfs_luks_close> on the C</dev/mapper/mapname> device (I<not> the "
"underlying encrypted block device)."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:525
msgid "INSPECTION"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:527
msgid ""
"Libguestfs has APIs for inspecting an unknown disk image to find out if it "
"contains operating systems. (These APIs used to be in a separate Perl-only "
"library called L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most "
"frequently used part of this library has been rewritten in C and moved into "
"the core code)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:533
msgid ""
"Add all disks belonging to the unknown virtual machine and call "
"L</guestfs_launch> in the usual way."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:536
msgid ""
"Then call L</guestfs_inspect_os>. This function uses other libguestfs calls "
"and certain heuristics, and returns a list of operating systems that were "
"found. An empty list means none were found. A single element is the root "
"filesystem of the operating system. For dual- or multi-boot guests, "
"multiple roots can be returned, each one corresponding to a separate "
"operating system. (Multi-boot virtual machines are extremely rare in the "
"world of virtualization, but since this scenario can happen, we have built "
"libguestfs to deal with it.)"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:545
msgid ""
"For each root, you can then call various C<guestfs_inspect_get_*> functions "
"to get additional details about that operating system. For example, call "
"L</guestfs_inspect_get_type> to return the string C<windows> or C<linux> for "
"Windows and Linux-based operating systems respectively."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:551
msgid ""
"Un*x-like and Linux-based operating systems usually consist of several "
"filesystems which are mounted at boot time (for example, a separate boot "
"partition mounted on C</boot>). The inspection rules are able to detect how "
"filesystems correspond to mount points. Call "
"C<guestfs_inspect_get_mountpoints> to get this mapping. It might return a "
"hash table like this example:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:558
#, no-wrap
msgid ""
" /boot => /dev/sda1\n"
" / => /dev/vg_guest/lv_root\n"
" /usr => /dev/vg_guest/lv_usr\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:562
msgid ""
"The caller can then make calls to L</guestfs_mount_options> to mount the "
"filesystems as suggested."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:565
msgid ""
"Be careful to mount filesystems in the right order (eg. C</> before "
"C</usr>). Sorting the keys of the hash by length, shortest first, should "
"work."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:569
msgid ""
"Inspection currently only works for some common operating systems. "
"Contributors are welcome to send patches for other operating systems that we "
"currently cannot detect."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:573
msgid ""
"Encrypted disks must be opened before inspection. See L</ENCRYPTED DISKS> "
"for more details. The L</guestfs_inspect_os> function just ignores any "
"encrypted devices."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:577
msgid ""
"A note on the implementation: The call L</guestfs_inspect_os> performs "
"inspection and caches the results in the guest handle. Subsequent calls to "
"C<guestfs_inspect_get_*> return this cached information, but I<do not> "
"re-read the disks. If you change the content of the guest disks, you can "
"redo inspection by calling L</guestfs_inspect_os> again. "
"(L</guestfs_inspect_list_applications> works a little differently from the "
"other calls and does read the disks. See documentation for that function "
"for details)."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:586
msgid "SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:588
msgid ""
"Libguestfs can mount NTFS partitions. It does this using the "
"L<http://www.ntfs-3g.org/> driver."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:591
msgid ""
"DOS and Windows still use drive letters, and the filesystems are always "
"treated as case insensitive by Windows itself, and therefore you might find "
"a Windows configuration file referring to a path like "
"C<c:\\windows\\system32>. When the filesystem is mounted in libguestfs, "
"that directory might be referred to as C</WINDOWS/System32>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:597
msgid ""
"Drive letter mappings are outside the scope of libguestfs. You have to use "
"libguestfs to read the appropriate Windows Registry and configuration files, "
"to determine yourself how drives are mapped (see also L<hivex(3)> and "
"L<virt-inspector(1)>)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:602
msgid ""
"Replacing backslash characters with forward slash characters is also outside "
"the scope of libguestfs, but something that you can easily do."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:605
msgid ""
"Where we can help is in resolving the case insensitivity of paths. For "
"this, call L</guestfs_case_sensitive_path>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:608
msgid ""
"Libguestfs also provides some help for decoding Windows Registry \"hive\" "
"files, through the library C<hivex> which is part of the libguestfs project "
"although ships as a separate tarball. You have to locate and download the "
"hive file(s) yourself, and then pass them to C<hivex> functions. See also "
"the programs L<hivexml(1)>, L<hivexsh(1)>, L<hivexregedit(1)> and "
"L<virt-win-reg(1)> for more help on this issue."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:616
msgid "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:618
msgid ""
"Although we don't want to discourage you from using the C API, we will "
"mention here that the same API is also available in other languages."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:621
msgid ""
"The API is broadly identical in all supported languages. This means that "
"the C call C<guestfs_mount(g,path)> is C<$g-E<gt>mount($path)> in Perl, "
"C<g.mount(path)> in Python, and C<Guestfs.mount g path> in OCaml. In other "
"words, a straightforward, predictable isomorphism between each language."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:627
msgid ""
"Error messages are automatically transformed into exceptions if the language "
"supports it."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:630
msgid ""
"We don't try to \"object orientify\" parts of the API in OO languages, "
"although contributors are welcome to write higher level APIs above what we "
"provide in their favourite languages if they wish."
msgstr ""
# type: =item
#: ../src/guestfs.pod:636
msgid "B<C++>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:638
msgid ""
"You can use the I<guestfs.h> header file from C++ programs. The C++ API is "
"identical to the C API. C++ classes and exceptions are not used."
msgstr ""
# type: =item
#: ../src/guestfs.pod:642
msgid "B<C#>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:644
msgid ""
"The C# bindings are highly experimental. Please read the warnings at the "
"top of C<csharp/Libguestfs.cs>."
msgstr ""
# type: =item
#: ../src/guestfs.pod:647
msgid "B<Haskell>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:649
msgid ""
"This is the only language binding that is working but incomplete. Only "
"calls which return simple integers have been bound in Haskell, and we are "
"looking for help to complete this binding."
msgstr ""
# type: =item
#: ../src/guestfs.pod:653
msgid "B<Java>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:655
msgid ""
"Full documentation is contained in the Javadoc which is distributed with "
"libguestfs."
msgstr ""
# type: =item
#: ../src/guestfs.pod:658
msgid "B<OCaml>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:660
msgid "For documentation see L<guestfs-ocaml(3)>."
msgstr ""
# type: =item
#: ../src/guestfs.pod:662
msgid "B<Perl>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:664
msgid "For documentation see L<Sys::Guestfs(3)>."
msgstr ""
# type: =item
#: ../src/guestfs.pod:666
msgid "B<PHP>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:668
msgid ""
"For documentation see C<README-PHP> supplied with libguestfs sources or in "
"the php-libguestfs package for your distribution."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:671
msgid "The PHP binding only works correctly on 64 bit machines."
msgstr ""
# type: =item
#: ../src/guestfs.pod:673
msgid "B<Python>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:675
msgid "For documentation see L<guestfs-python(3)>."
msgstr ""
# type: =item
#: ../src/guestfs.pod:677
msgid "B<Ruby>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:679
msgid "For documentation see L<guestfs-ruby(3)>."
msgstr ""
# type: =item
#: ../src/guestfs.pod:681
msgid "B<shell scripts>"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:683
msgid "For documentation see L<guestfish(1)>."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:687
msgid "LIBGUESTFS GOTCHAS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:689
msgid ""
"L<http://en.wikipedia.org/wiki/Gotcha_(programming)>: \"A feature of a "
"system [...] that works in the way it is documented but is counterintuitive "
"and almost invites mistakes.\""
msgstr ""
# type: textblock
#: ../src/guestfs.pod:693
msgid ""
"Since we developed libguestfs and the associated tools, there are several "
"things we would have designed differently, but are now stuck with for "
"backwards compatibility or other reasons. If there is ever a libguestfs 2.0 "
"release, you can expect these to change. Beware of them."
msgstr ""
# type: =item
#: ../src/guestfs.pod:701
msgid "Autosync / forgetting to sync."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:703
msgid ""
"When modifying a filesystem from C or another language, you B<must> unmount "
"all filesystems and call L</guestfs_sync> explicitly before you close the "
"libguestfs handle. You can also call:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:707
#, no-wrap
msgid ""
" guestfs_set_autosync (g, 1);\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:709
msgid ""
"to have the unmount/sync done automatically for you when the handle 'g' is "
"closed. (This feature is called \"autosync\", L</guestfs_set_autosync> "
"q.v.)"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:713
msgid ""
"If you forget to do this, then it is entirely possible that your changes "
"won't be written out, or will be partially written, or (very rarely) that "
"you'll get disk corruption."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:717
msgid ""
"Note that in L<guestfish(3)> autosync is the default. So quick and dirty "
"guestfish scripts that forget to sync will work just fine, which can make "
"this very puzzling if you are trying to debug a problem."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:721
msgid ""
"Update: Autosync is enabled by default for all API users starting from "
"libguestfs 1.5.24."
msgstr ""
# type: =item
#: ../src/guestfs.pod:724
msgid "Mount option C<-o sync> should not be the default."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:726
msgid ""
"If you use L</guestfs_mount>, then C<-o sync,noatime> are added implicitly. "
"However C<-o sync> does not add any reliability benefit, but does have a "
"very large performance impact."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:730
msgid ""
"The work around is to use L</guestfs_mount_options> and set the mount "
"options that you actually want to use."
msgstr ""
# type: =item
#: ../src/guestfs.pod:733
msgid "Read-only should be the default."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:735
msgid ""
"In L<guestfish(3)>, I<--ro> should be the default, and you should have to "
"specify I<--rw> if you want to make changes to the image."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:738
msgid "This would reduce the potential to corrupt live VM images."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:740
msgid ""
"Note that many filesystems change the disk when you just mount and unmount, "
"even if you didn't perform any writes. You need to use "
"L</guestfs_add_drive_ro> to guarantee that the disk is not changed."
msgstr ""
# type: =item
#: ../src/guestfs.pod:744
msgid "guestfish command line is hard to use."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:746
msgid ""
"C<guestfish disk.img> doesn't do what people expect (open C<disk.img> for "
"examination). It tries to run a guestfish command C<disk.img> which doesn't "
"exist, so it fails. In earlier versions of guestfish the error message was "
"also unintuitive, but we have corrected this since. Like the Bourne shell, "
"we should have used C<guestfish -c command> to run commands."
msgstr ""
# type: =item
#: ../src/guestfs.pod:753
msgid "guestfish megabyte modifiers don't work right on all commands"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:755
msgid ""
"In recent guestfish you can use C<1M> to mean 1 megabyte (and similarly for "
"other modifiers). What guestfish actually does is to multiply the number "
"part by the modifier part and pass the result to the C API. However this "
"doesn't work for a few APIs which aren't expecting bytes, but are already "
"expecting some other unit (eg. megabytes)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:762
msgid "The most common is L</guestfs_lvcreate>. The guestfish command:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:764
#, no-wrap
msgid ""
" lvcreate LV VG 100M\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:766
msgid ""
"does not do what you might expect. Instead because L</guestfs_lvcreate> is "
"already expecting megabytes, this tries to create a 100 I<terabyte> (100 "
"megabytes * megabytes) logical volume. The error message you get from this "
"is also a little obscure."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:771
msgid ""
"This could be fixed in the generator by specially marking parameters and "
"return values which take bytes or other units."
msgstr ""
# type: =item
#: ../src/guestfs.pod:774
msgid "Ambiguity between devices and paths"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:776
msgid ""
"There is a subtle ambiguity in the API between a device name "
"(eg. C</dev/sdb2>) and a similar pathname. A file might just happen to be "
"called C<sdb2> in the directory C</dev> (consider some non-Unix VM image)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:781
msgid ""
"In the current API we usually resolve this ambiguity by having two separate "
"calls, for example L</guestfs_checksum> and L</guestfs_checksum_device>. "
"Some API calls are ambiguous and (incorrectly) resolve the problem by "
"detecting if the path supplied begins with C</dev/>."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:787
msgid ""
"To avoid both the ambiguity and the need to duplicate some calls, we could "
"make paths/devices into structured names. One way to do this would be to "
"use a notation like grub (C<hd(0,0)>), although nobody really likes this "
"aspect of grub. Another way would be to use a structured type, equivalent "
"to this OCaml type:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:793
#, no-wrap
msgid ""
" type path = Path of string | Device of int | Partition of int * int\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:795
msgid "which would allow you to pass arguments like:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:797
#, no-wrap
msgid ""
" Path \"/foo/bar\"\n"
" Device 1 (* /dev/sdb, or perhaps /dev/sda *)\n"
" Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)\n"
" Path \"/dev/sdb2\" (* not a device *)\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:802
msgid ""
"As you can see there are still problems to resolve even with this "
"representation. Also consider how it might work in guestfish."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:807
msgid "PROTOCOL LIMITS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:809
msgid ""
"Internally libguestfs uses a message-based protocol to pass API calls and "
"their responses to and from a small \"appliance\" (see L</INTERNALS> for "
"plenty more detail about this). The maximum message size used by the "
"protocol is slightly less than 4 MB. For some API calls you may need to be "
"aware of this limit. The API calls which may be affected are individually "
"documented, with a link back to this section of the documentation."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:817
msgid ""
"A simple call such as L</guestfs_cat> returns its result (the file data) in "
"a simple string. Because this string is at some point internally encoded as "
"a message, the maximum size that it can return is slightly under 4 MB. If "
"the requested file is larger than this then you will get an error."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:823
msgid ""
"In order to transfer large files into and out of the guest filesystem, you "
"need to use particular calls that support this. The sections L</UPLOADING> "
"and L</DOWNLOADING> document how to do this."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:827
msgid ""
"You might also consider mounting the disk image using our FUSE filesystem "
"support (L<guestmount(1)>)."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:830
msgid "KEYS AND PASSPHRASES"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:832
msgid ""
"Certain libguestfs calls take a parameter that contains sensitive key "
"material, passed in as a C string."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:835
msgid ""
"In the future we would hope to change the libguestfs implementation so that "
"keys are L<mlock(2)>-ed into physical RAM, and thus can never end up in "
"swap. However this is I<not> done at the moment, because of the complexity "
"of such an implementation."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:840
msgid ""
"Therefore you should be aware that any key parameter you pass to libguestfs "
"might end up being written out to the swap partition. If this is a concern, "
"scrub the swap partition or don't use libguestfs on encrypted devices."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:845
msgid "MULTIPLE HANDLES AND MULTIPLE THREADS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:847
msgid ""
"All high-level libguestfs actions are synchronous. If you want to use "
"libguestfs asynchronously then you must create a thread."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:850
msgid ""
"Only use the handle from a single thread. Either use the handle exclusively "
"from one thread, or provide your own mutex so that two threads cannot issue "
"calls on the same handle at the same time."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:854
msgid ""
"See the graphical program guestfs-browser for one possible architecture for "
"multithreaded programs using libvirt and libguestfs."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:857
msgid "PATH"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:859
msgid ""
"Libguestfs needs a kernel and initrd.img, which it finds by looking along an "
"internal path."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:862
msgid ""
"By default it looks for these in the directory C<$libdir/guestfs> "
"(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>)."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:865
msgid ""
"Use L</guestfs_set_path> or set the environment variable L</LIBGUESTFS_PATH> "
"to change the directories that libguestfs will search in. The value is a "
"colon-separated list of paths. The current directory is I<not> searched "
"unless the path contains an empty element or C<.>. For example "
"C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would search the current directory and "
"then C</usr/lib/guestfs>."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:872
msgid "QEMU WRAPPERS"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:874
msgid ""
"If you want to compile your own qemu, run qemu from a non-standard location, "
"or pass extra arguments to qemu, then you can write a shell-script wrapper "
"around qemu."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:878
msgid ""
"There is one important rule to remember: you I<must C<exec qemu>> as the "
"last command in the shell script (so that qemu replaces the shell and "
"becomes the direct child of the libguestfs-using program). If you don't do "
"this, then the qemu process won't be cleaned up correctly."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:883
msgid ""
"Here is an example of a wrapper, where I have built my own copy of qemu from "
"source:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:886
#, no-wrap
msgid ""
" #!/bin/sh -\n"
" qemudir=/home/rjones/d/qemu\n"
" exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "
"\"$@\"\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:890
msgid ""
"Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>, and "
"then use it by setting the LIBGUESTFS_QEMU environment variable. For "
"example:"
msgstr ""
# type: verbatim
#: ../src/guestfs.pod:894
#, no-wrap
msgid ""
" LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish\n"
"\n"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:896
msgid ""
"Note that libguestfs also calls qemu with the -help and -version options in "
"order to determine features."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:899
msgid "ABI GUARANTEE"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:901
msgid ""
"We guarantee the libguestfs ABI (binary interface), for public, high-level "
"actions as outlined in this section. Although we will deprecate some "
"actions, for example if they get replaced by newer calls, we will keep the "
"old actions forever. This allows you the developer to program in confidence "
"against the libguestfs API."
msgstr ""
# type: =head2
#: ../src/guestfs.pod:907
msgid "BLOCK DEVICE NAMING"
msgstr ""
# type: textblock
#: ../src/guestfs.pod:909
msgid ""
"In the kernel there is now quite a profusion of schemata for naming block "
"devices (in this context, by I<block device> I mean a physical or virtual "
"hard drive). The original Linux IDE driver used names starting with "
"C</dev/hd*>. SCSI devices have historically used a different naming scheme, "
"C</dev/sd*>. When the Linux kernel I<libata> driver became a popular "
"replacement for the old IDE driver (particularly for SATA devices) those "
"devices also used the C</dev/sd*> scheme. Additionally we now have virtual "
"machines with paravirtualized drivers. This has created several different "
"naming systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for "
"Xen PV disks."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:921
msgid ""
"As discussed above, libguestfs uses a qemu appliance running an embedded "
"Linux kernel to access block devices. We can run a variety of appliances "
"based on a variety of Linux kernels."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:925
msgid ""
"This causes a problem for libguestfs because many API calls use device or "
"partition names. Working scripts and the recipe (example) scripts that we "
"make available over the internet could fail if the naming scheme changes."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:930
msgid ""
"Therefore libguestfs defines C</dev/sd*> as the I<standard naming scheme>. "
"Internally C</dev/sd*> names are translated, if necessary, to other names as "
"required. For example, under RHEL 5 which uses the C</dev/hd*> scheme, any "
"device parameter C</dev/sda2> is translated to C</dev/hda2> transparently."
msgstr ""
# type: textblock
#: ../src/guestfs.pod:936
msgid ""
"Note that this I<only> applies to parameters. The L</guestfs_list_devices>, "
"L</guestfs_list_partitions> and similar calls return the true names of the "
"devices and partitions as known to the appliance."
| 