docs: Routine refresh of the documentation for guestfs(3) and guestfish(1).
[libguestfs.git] / tools / virt-cat
1 #!/usr/bin/perl -w
2 # virt-cat
3 # Copyright (C) 2009 Red Hat Inc.
4 #
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2 of the License, or
8 # (at your option) any later version.
9 #
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 # GNU General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with this program; if not, write to the Free Software
17 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18
19 use warnings;
20 use strict;
21
22 use Sys::Guestfs;
23 use Sys::Guestfs::Lib qw(open_guest get_partitions resolve_windows_path
24   inspect_all_partitions inspect_partition
25   inspect_operating_systems mount_operating_system);
26 use Pod::Usage;
27 use Getopt::Long;
28 use Locale::TextDomain 'libguestfs';
29
30 =encoding utf8
31
32 =head1 NAME
33
34 virt-cat - Display a file in a virtual machine
35
36 =head1 SYNOPSIS
37
38  virt-cat [--options] domname file
39
40  virt-cat [--options] disk.img [disk.img ...] file
41
42 =head1 DESCRIPTION
43
44 C<virt-cat> is a command line tool to display the contents of C<file>
45 where C<file> exists in the named virtual machine (or disk image).
46
47 C<virt-cat> can be used to quickly view a single file.  To edit a
48 file, use C<virt-edit>.  For more complex cases you should look at the
49 L<guestfish(1)> tool.
50
51 =head1 EXAMPLES
52
53 Display C</etc/fstab> file from inside the libvirt VM called
54 C<mydomain>:
55
56  virt-cat mydomain /etc/fstab
57
58 List syslog messages from a VM:
59
60  virt-cat mydomain /var/log/messages | tail
61
62 Find out what DHCP IP address a VM acquired:
63
64  virt-cat mydomain /var/log/messages | grep 'dhclient: bound to' | tail
65
66 Find out what packages were recently installed:
67
68  virt-cat mydomain /var/log/yum.log | tail
69
70 Find out who is logged on inside a virtual machine:
71
72  virt-cat mydomain /var/run/utmp > /tmp/utmp
73  who /tmp/utmp
74
75 or who was logged on:
76
77  virt-cat mydomain /var/log/wtmp > /tmp/wtmp
78  last -f /tmp/wtmp
79
80 =head1 OPTIONS
81
82 =over 4
83
84 =cut
85
86 my $help;
87
88 =item B<--help>
89
90 Display brief help.
91
92 =cut
93
94 my $version;
95
96 =item B<--version>
97
98 Display version number and exit.
99
100 =cut
101
102 my $uri;
103
104 =item B<--connect URI> | B<-c URI>
105
106 If using libvirt, connect to the given I<URI>.  If omitted, then we
107 connect to the default libvirt hypervisor.
108
109 If you specify guest block devices directly, then libvirt is not used
110 at all.
111
112 =back
113
114 =cut
115
116 GetOptions ("help|?" => \$help,
117             "version" => \$version,
118             "connect|c=s" => \$uri,
119     ) or pod2usage (2);
120 pod2usage (1) if $help;
121 if ($version) {
122     my $g = Sys::Guestfs->new ();
123     my %h = $g->version ();
124     print "$h{major}.$h{minor}.$h{release}$h{extra}\n";
125     exit
126 }
127
128 pod2usage (__"virt-cat: no image, VM names or filenames to cat given")
129     if @ARGV <= 1;
130
131 my $filename = pop @ARGV;
132
133 my $g;
134 if ($uri) {
135     $g = open_guest (\@ARGV, address => $uri);
136 } else {
137     $g = open_guest (\@ARGV);
138 }
139
140 $g->launch ();
141
142 # List of possible filesystems.
143 my @partitions = get_partitions ($g);
144
145 # Now query each one to build up a picture of what's in it.
146 my %fses =
147     inspect_all_partitions ($g, \@partitions,
148       use_windows_registry => 0);
149
150 my $oses = inspect_operating_systems ($g, \%fses);
151
152 my @roots = keys %$oses;
153 die __"no root device found in this operating system image" if @roots == 0;
154 die __"multiboot operating systems are not supported by virt-cat" if @roots > 1;
155 my $root_dev = $roots[0];
156
157 my $os = $oses->{$root_dev};
158 mount_operating_system ($g, $os);
159
160 # Allow this to fail in case eg. the file does not exist.
161 # NB: https://bugzilla.redhat.com/show_bug.cgi?id=501888
162 print $g->download($filename, "/dev/stdout");
163
164 =head1 SEE ALSO
165
166 L<guestfs(3)>,
167 L<guestfish(1)>,
168 L<virt-edit(1)>,
169 L<Sys::Guestfs(3)>,
170 L<Sys::Guestfs::Lib(3)>,
171 L<Sys::Virt(3)>,
172 L<http://libguestfs.org/>.
173
174 =head1 AUTHOR
175
176 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
177
178 =head1 COPYRIGHT
179
180 Copyright (C) 2009 Red Hat Inc.
181
182 This program is free software; you can redistribute it and/or modify
183 it under the terms of the GNU General Public License as published by
184 the Free Software Foundation; either version 2 of the License, or
185 (at your option) any later version.
186
187 This program is distributed in the hope that it will be useful,
188 but WITHOUT ANY WARRANTY; without even the implied warranty of
189 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
190 GNU General Public License for more details.
191
192 You should have received a copy of the GNU General Public License
193 along with this program; if not, write to the Free Software
194 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.