1 2=head1 NAME 3 4NetApp::Filer -- OO Class for managing NetApp Filer devices 5 6=head1 SYNOPSIS 7 8 use NetApp::Filer; 9 10 my $filer = NetApp::Filer->new({ 11 hostname => $hostname_of_nasfiler, 12 ssh_identity => "/path/to/ssh/identify/file", 13 }); 14 15 my $filer = NetApp::Filer->new({ 16 hostname => $hostname_of_nasfiler, 17 protocol => 'telnet', 18 telnet_password => $telnet_password, 19 }); 20 21=head1 DESCRIPTION 22 23This class implements methods for communication with a NetApp Filer 24device. Both ssh and telnet are supported, but only ssh is really 25recommended. NetApp doesn't support concurrent access via telnet, and 26the error checking using ssh is far more robust. Not to mention, you 27can configure secure access via ssh without using passwords, but 28telnet access will always require a password. 29 30=head1 METHODS 31 32=head2 Filer Specific Methods 33 34=head3 new( $args_ref ) 35 36This method takes a hash reference of arguments, and returns a 37NetApp::Filer object to be used to communicate with the specified 38filer. 39 40The arguments are as follows: 41 42 NetApp::Filer->new({ 43 # Required arguments 44 hostname => $hostname, 45 # Optional arguments 46 username => $username, 47 ssh_identify => $ssh_identity, 48 ssh_command => [ @ssh_command ], 49 protocol => 'ssh' | 'telnet', 50 telnet_password => $telnet_password, 51 telnet_timeout => $telnet_timeout, 52 cache_enabled => 0 || 1, 53 cache_expiration => $cache_expiration, 54 }); 55 56=over 57 58=item (required) hostname 59 60The value of this argument is a string, which is the hostname of the 61filer to connect to. 62 63=item (optional) username 64 65The username to use for communication. Defaults to 'root'. 66 67=item (optional) ssh_identify 68 69The ssh identify file to use for ssh communication. If not specified 70then ssh will be invoked without the -i argument, and will use 71whatever default identify file is setup for the current user. 72 73In practice, this argument will almost always be required, but the 74code allows it to be optional. 75 76If the specified file doesn't exist, then a fatal exception is raised. 77 78=item (optional) ssh_command 79 80An array reference representing the ssh command to be used to 81communication. Defaults to just ['ssh']. 82 83Don't use this argument to specify the identity via -i. Instead, use 84the ssh_identify argument. If you need to specify certain ssh 85options, for example StrictHostKeyChecking, then use this argument. 86For example: 87 88 my $filer = NetApp::Filer->new({ 89 hostname => $somenasfiler, 90 ssh_command => [qw( ssh -o StrictHostKeyChecking=no )], 91 }); 92 93=item (optional) protocol 94 95This option is a string, either 'ssh' or 'telnet'. The default, and 96recommended, protocol is ssh. While telnet is supported, only one 97concurrent root telnet session per filer is allowed, and the error 98checking over telnet is far less robust than ssh. 99 100=item (optional) telnet_password 101 102This option is a string, and specified the root password to use when 103connecting via telnet. Note that password based ssh connectivity is 104not supported, and telnet access, while supported, is not recommended. 105The author uses the telnet support for only one thing: installing the 106ssh keys, and configuring ssh access. 107 108=item (optional) cache_enabled 109 110NOTE: The caching mechanism is considered experimental. For one 111thing, it depends on using a patched version of Memoize::Expire, which 112is still not yet available on CPAN. Use with caution. 113 114This option has a boolean value, and is used to disable the internal 115caching of the results of several API calls. By default, the cache is 116disabled. If enabled, then the result of any of the following 117NetApp::Filer methods will be cached, using Memoize: 118 119 get_aggregate 120 get_volume 121 get_qtree 122 123To enable caching of these API calls, set cache_enabled to a true 124value. The cached values will expire (see the next option), unless 125the expiration value is set to 0. 126 127=item (optional) cache_expiration 128 129This option is an integer, and is the number of seconds to cache 130results of the above API calls. The default value is 10 seconds. 131Setting this value to 0 will prevent the cached values from expiring 132at all. 133 134=back 135 136=head3 get_version 137 138Returns a NetApp::Filer::Version object. 139 140=head3 get_licenses 141 142Returns a list of NetApp::Filer::License objects, each of which 143represents a single licensed service on the filer. Note that if the 144service is "not licensed", it is ignored. Only services with active 145of expired licensed are returned. 146 147=head3 get_license( $service ) 148 149Returns a single NetApp::Filer::License object for the specified service. 150 151=head3 add_license( $code ) 152 153Adds a license using the specified code. Returns a boolean value only. 154 155=head3 delete_license( $service ) 156 157Deleted the license for the specified service. Returns a boolean value only. 158 159=head2 Aggregate Specific Methods 160 161=head3 get_aggregate_names 162 163Returns a list of strings, each of which is the name of an aggregate 164on the filer. 165 166=head3 get_aggregates 167 168Returns a list of NetApp::Aggregate objects, each of which represents 169an aggregate on the filer. 170 171=head3 get_aggregate( $name ) 172 173Returns a single NetApp::Aggregate object for the specified aggregate 174name. 175 176=head3 create_aggregate( %args ) 177 178Create an aggregate using the specified arguments, and returns the 179NetApp::Aggregate object that represents it. The arguments are as 180follows: 181 182 my $aggregate = $filer->create_aggregate( 183 # Required arguments 184 name => $name, 185 # Optional arguments 186 raidtype => 'raid0' | 'raid4' | 'raid_dp', 187 raidsize => $raidsize, 188 disktype => 'ATA' | 'FCAL' | 'LUN' | 'SAS' | 'SATA' | 'SCSI', 189 diskcount => $diskcount, 190 disksize => $disksize, 191 rpm => $rpm, 192 language => $language, 193 snaplock => 'Compliance' | 'Enterprise', 194 mirrored => 1, # -m 195 traditional => 1, # -v 196 force => 1, # -f 197 disks => [ 198 # To specify a single set of disks: 199 'disk1', 'disk2', .... 200 # To specify two sets of disks: 201 [ 'disk1', 'disk2', .... ], 202 [ 'diskn', 'disktn+1', .... ], 203 ], 204 ); 205 206=head3 destroy_aggregate( %args ) 207 208Destroy an aggregate using the specified arguments. The arguments are 209as follows: 210 211 $filer->destroy_aggregate( 212 # Required arguments 213 name => $name, 214 ); 215 216=head2 Volume Specific Methods 217 218=head3 get_volume_names 219 220Returns a list of strings, each of which is the name of a volume on 221the filer. 222 223=head3 get_volumes 224 225Returns a list of NetApp::Volume objects, each of which represents a 226volume on the filer. 227 228=head3 get_volume( $name ) 229 230Returns a single NetApp::Volume object for the specified volume name. 231 232=head2 Qtree Specific Methods 233 234=head3 get_qtree_names 235 236Returns a list of strings, each of which is the name of a qtree on the 237filer. 238 239=head3 get_qtrees 240 241Returns a list of NetApp::Qtree objects, each of which represents a 242single qtree on the filer. 243 244=head3 get_qtree( $name ) 245 246Returns a single NetApp::Qtree object for the specified qtree 247name. The name must in the form of a pathname, for example: 248 249 /vol/volume_name/qtree_name 250 251The qtree_name is optional if querying the object for a volume's qtree. 252 253=head3 create_qtree( %args ) 254 255Creates a qtree on the filer. The arguments are as follows: 256 257 $filer->create_qtree( 258 # Required arguments 259 name => $name, 260 # Optional arguments 261 mode => $mode, 262 security => 'unix' | 'ntfs' | 'mixed', 263 oplocks => 0 | 1, 264 ); 265 266=over 267 268=item (required) name 269 270The name of the qtree to create. 271 272=item (optional) mode 273 274The UNIX mode bits to use when creating the qtree. 275 276=item (optional) security 277 278The security of the qtree. This must be one of: unix, ntfs, or mixed. 279 280=item (optional) oplocks 281 282This option specified whether or not oplocks are to be enabled on the 283qtree. The value is interpreted in a boolean context, true meaning 284"enabled" and false meaning "disabled". 285 286=back 287 288=head2 Snapmirror Specific Methods 289 290=head3 set_snapmirror_state( $state ) 291 292Sets the snapmirror state on the filer to the specified value, which 293must be either of the strings "off" or "on". 294 295=head3 get_snapmirror_state 296 297Returns a string, either "off" or "on", indicating whether or not 298snapmirror is turned off or on for this filer. 299 300=head3 get_snapmirrors 301 302Returns a list of NetApp::Snapmirror objecte, each of which represents 303a single snapmirror relationship on the filer. 304 305=head2 Export Specific Methods 306 307There is one general purpose method to retrieve all of the NFS exports 308on a filer, and 4 special purpose ones that make it easy to see the 309difference between the contents of /etc/exports, and the live exports 310reported by "exportfs". 311 312=head3 get_exports 313 314Returns a list of NetApp::Filer::Export objects, each of which 315represents an NFS export on the filer. 316 317=head3 get_permanent_exports 318 319Returns a list of NetApp::Filer::Export objects, each of which 320represents a permanent export, which is one found in the /etc/exports 321file. 322 323=head3 get_temporary_exports 324 325Returns a list of NetApp::Filer::Export objects, each of which 326represents a temporary export, which is one NOT found in the 327/etc/exports file. Temporary exports are ones created manually, using 328"exportfs -io", or by using the "exportfs -b" option to fence clients, 329or any other command which creates a live NFS export that has not yet 330been written to /etc/exports, and which will not survive a reboot of 331the filer. 332 333=head3 get_active_exports 334 335Returns a list of NetApp::Filer::Export objects, each of which 336represents a active export. Active exports are those reported by the 337"exportfs" command. They can be permanent, if they are found in 338/etc/exports, or temporary, if created by hand. 339 340=head3 get_inactive_exports 341 342Returns a list of NetApp::Filer::Export objects, each of which 343represents a inactive export. An inactive export is a permanent 344export found in /etc/exports, but which is NOT found in the list of 345active exports reported by "exportfs". If the options of a permanent 346export are changed, but not saved to /etc/exports (eg. re-export 347something with "exportfs -io"), then the active, temporary export for 348that same path, and the inactive, permanent export in /etc/exports can 349both exist concurrently. 350 351=cut 352