Rotate(3pm)

📦
version 1.04 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

Logfile::Rotate — a Perl module to rotate logfiles, bestie. That's it, that's the whole vibe. 💫

✨ SYNOPSIS ✨

use Logfile::Rotate;
my $log = new Logfile::Rotate( File   => '/var/adm/syslog/syslog.log',
                               Count  => 7,
                               Gzip  => 'lib',
                               Post   => sub{
                                 open(IN, "/var/run/syslog.pid");
                                 kill("HUP", chomp(<IN>)); }
                               Dir    => '/var/log/old',
                               Flock  => 'yes',
                               Persist => 'yes',
                             );

# process log file

$log->rotate();

or

my $log = new Logfile::Rotate( File  => '/var/adm/syslog',
                               Gzip   => '/usr/local/bin/gzip');

# process log file

$log->rotate();
undef $log;

Like… two whole ways to do it. Pick your fighter. 🥊

💅 DESCRIPTION 💅

Okay so real talk: the author used the name space of the Logfile::Base package by Ulrich Pfeifer, because using this module is very closely related to processing logfiles. Sibling energy fr fr. 🫶

🌸 new

new accepts the following arguments: File, Count, Gzip, Pre, Post, Flock and Dir — and literally only File is mandatory. The rest are just there if you want them, no pressure, slay.

new will open and lock the file, so you can co-ordinate the processing of the file with rotating it. The file gets closed and unlocked when the object is destroyed, so if you wanna do that yourself, just go ahead and undef the object explicitly. Main character move. ✨

The Pre/Post arguments let you pass function references to this method, and you can use them as a callback for any processing you want before or after the rotation. For example, you may notify the process writing to the file that it has been rotated. Very "hey bestie, heads up" of you. 📣

The Pre function is passed the current filename to be rotated as an argument, and the Post function is passed the current filename that was rotated and that file's new filename — including any extension added by compression previously.

Both the Pre and Post function references you provide are executed within an eval statement inside the rotate method. And if that eval returns an error, then the rotate method will croak at that point. 😭 So keep them clean, okay?

The Signal argument is deprecated by the Post argument. Old news, move on. 💀

The Flock argument lets you specify whether the perl function flock is used to lock the file during the rotation operation. Apparently flock causes problems on some platforms, and this option was added so you can control the program's behaviour. By default the file will be locked using flock.

The Persist argument lets you control whether the program will try and set the current log file ownership and permissions on any new files that may be created by the rotation. In some circumstances the program doing the file rotation may not have sufficient permission to chown on the file. By default the program will try and preserve ownership and permissions. Periodt. 💅

🔥 rotate()

This method will copy the file passed in new to a file of the same name, with a numeric extension, and truncate the original file to zero length. Iconic, honestly.

The numeric extension will range from 1 up to the value specified by Count, or 7 if none is defined, with 1 being the most recent file. When Count is reached, the older file is discarded in a FIFO (first in, first out) fashion. Got it? First in, first out — no cutting the line. 🎟️

If the argument Dir was given, all old files will be placed in the specified directory.

The Post function is the last step executed by the rotate method, so the return code of rotate will be the return code of the function you provided — or 1 by default.

The copy function is implemented by using the File::Copy package, but a few people have suggested they'd prefer File::Move. The author is still not decided on this, because you would lose data if the move should fail. Big yikes, so it makes sense. 🙈

🌈 Optional Compression

If available, rotate will also compress the file with the gzip program, or the program passed as the Gzip argument.

You may now also use lib as a value for the Gzip argument. This directs the program to load the Compress::Zlib module, if available, and use it to do the compression within perl. This avoids the security issues associated with spawning external programs and is the recommended value for this option. Chef's kiss. 👑

If no argument is defined, it will first check to see if the Compress::Zlib module can be loaded, then check the perl Config to determine if gzip is available on your system. In this case the gzip must be in your current path to succeed, and accept the -f option.

See the WARNING section below. 👀

🦋 Optional Relocation Directory

If you specify an argument for Dir, then the file being rotated will be relocated to the directory specified — along with any other files that may have been rotated previously.

If the directory name specified does not exist, then it will be created with 0750 permissions. If you wish to have other permissions on the directory, then the author would recommend you create the directory before using this module.

See the WARNING section below. 👀 (again, but for a different reason)

⚠️ WARNING ⚠️

If a system call is made to gzip, this makes this module vulnerable to security problems if a rogue gzip is in your path, or if gzip has been sabotaged. For this reason I STRONGLY RECOMMEND you DO NOT use this module while you are ROOT. Like, genuinely. Do not. 🚨

For a more secure alternative, install the Compress::Zlib module and use the lib value for the Gzip argument.

If you specify an argument for Dir and the directory name you pass does not exist, this module will create the directory with permissions 0750.

📦 DEPENDANCIES 📦

See File::Copy.

If Gzip is being used, it must create files with an extension of .gz for the file to be picked by the rotate cycle. If it doesn't do that, the rotation literally cannot see it. 🫠

Copyright (c) 1997-99 Paul Gampe. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN ``AS IS'' BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

(Yeah it's in all caps, that's just how the legal girlies write. Read it, don't fear it. 💜)

👀 SEE ALSO 👀

File::Copy, Logfile::Base, flock, and the Changes file for change history and credits for contributions. Go read the lore, iykyk. 📚

🎯 RETURN 🎯

All functions return 1 on success, 0 on failure. Binary. Simple. Correct. ✨

💖 AUTHOR 💖

Paul Gampe <paulg@apnic.net>

And that's the whole page, bestie — written up under perl v5.36.0, dated 2022-10-13. Go forth and rotate those logs responsibly. No cap. 🫶💅🌸

📦 where this page comes from