-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathlibfaketime.8
235 lines (224 loc) · 6.66 KB
/
libfaketime.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
.\" libfaketime.8 --
.\"
.\" Copyright (C) 2002-2004,2023 Krzysztof Burghardt <krzysztof@burghardt.pl>.
.\"
.TH LIBFAKETIME 8 "19 Feb 2023" "Linux`s Utilities" "Linux Users` Manual"
.SH NAME
libfaketime \- a library that adds a filter to time() function calls
.SH SYNOPSIS
.BI "it`s a library so you cannot execute it directly"
.SH DESCRIPTION
.B libfaketime
is a
.BR SO\ library
that provides filters in the
.BR time()
function.
.SS
libfaketime features:
.HP
- returns real or fake time to programs,
.HP
- has user-wide (~/.libfaketime.d/) and system-wide (/etc/libfaketime.d/) configuration,
.HP
- works transparently for programs,
.SH OPTIONS
Library does not need any options.
.SH Where\ to\ get\ libfaketime
.PP
The source code for libfaketime can be found at
https://github.com/burghardt/libfaketime
.SH Installing\ libfaketime
.TP 3
.TP
1.
If you install libfaketime on Linux, ensure that your shared loader
(ld-linux.so.1/ld.so) supports \fR\&\f(CWLD_PRELOAD\fR.
Recommended ld.so version 1.8.5 or never.
.TP
2.
Change cwd to the source code directory.
.TP
3.
Type \fR\&\f(CWmake\fR to compile and build libfaketime.so.1.
.TP
4.
Type \fR\&\f(CWmake install\fR to install the libfaketime library and manual
in their final destination locations.
.TP
5.
To use libfaketime, set the environment variable \fR\&\f(CWLD_PRELOAD\fR to
point to the libfaketime library. Example (sh syntax):
.IP
.nf
.ft 3
.in +0.3i
LD_PRELOAD=libfaketime.so.1
export LD_PRELOAD
.fi
.in -0.3i
.ft R
.lp
\&\fR
.IP
or (csh syntax):
.IP
.nf
.ft 3
.in +0.3i
setenv LD_PRELOAD libfaketime.so.1
.fi
.in -0.3i
.ft R
.lp
.IP
You might want to put these lines in your \fR\&\f(CW.profile\fR or
\&\fR\&\f(CW.cshrc\fR in order to activate libfaketime for all processes that you
initiate.
.TP
6.
Use your programs as you would normally. The libfaketime will transparently check the
time() callers, and if detected that should report fake time will change the cloc value for this program.
If a filtered time() is used, the following will occur:
.RS
.PD 0
.TP 3
1.
If the library detects that fake time should be returned and syslog support was enabled an entry will be added to /var/log/messages.
The following is an example of such an entry:
.RS
Mar 26 20:20:22 techie Libfaketime: using FAKE time() for (date:14654) UID(500) EUID(0)
.RE
.TP
2.
If the library cannot get fake time, and -DKILLER was defined in compile flags library will call _exit().
(To prevent making timestamps.)
.TP
.RE
.BR
.PP
For security reasons, the dynamic loader disregards environmental
variables such as \fR\&\f(CWLD_PRELOAD\fR when executing set-uid programs.
However, on Linux, you can use libfaketime with set-uid programs too, by using
one of the two methods described below:
.TP 3
1.
You may append the path to \fR\&libfaketime.so.1\fR into
\&\fR\&\f(CW/etc/ld.so.preload\fR instead of using
\fR\&\f(CWLD_PRELOAD\fR.
.IP
\&\fBWARNING\fR: If you use \fR\&\f(CW/etc/ld.so.preload\fR, be sure to
install \fR\&\f(CWlibfaketime.so.1\fR on your root filesystem, for
instance in \&\fR\&\f(CW/lib\fR, as is done by the default installation. Using
a directory which is not available at boot time, such as /usr/local/lib will
cause trouble at the next reboot! You also must not define -DKILLER if you want
to use libfaketime loaded from \fR\&\f(CW/etc/ld.so.preload\fR, because it will
attempt to kill your /sbin/init process when booting.
.IP
You should also be careful to remove libfaketime from
\fR\&\f(CW/etc/ld.so.preload\fR when installing a new version. First
test it out using \fR\&\f(CWLD_PRELOAD\fR, and only if everything is OK, put it
back into \&\fR\&\f(CW/etc/ld.so.preload\fR.
.TP
2.
If you have a version of \fR\&\f(CWld.so\fR which is more recent than
\&\fR\&\f(CW1.9.0\fR, you can set \fR\&\f(CWLD_PRELOAD\fR to contain the
basename of \fR\&\f(CWlibfaketime.so.1\fR without the directory. In that
case, the file is found as long as it is in the shared library path
(usually containing \fR\&\f(CW/lib\fR and \fR\&\f(CW/usr/lib\fR)).
Because the search is restricted to the library search path, this also works
for set-uid programs.
Example (sh syntax):
.IP
.nf
.ft 3
.in +0.3i
LD_PRELOAD=libfaketime.so.1
export LD_PRELOAD
.fi
.in -0.3i
.ft R
.lp
\&\fR
.IP
or (csh syntax):
.IP
.nf
.ft 3
.in +0.3i
setenv LD_PRELOAD libfaketime.so.1
.fi
.in -0.3i
.ft R
.lp
\&\fR
.IP
The advantage of this approach over \fR\&\f(CWld.so.preload\fR is that
libfaketime can more easily be switched off in case something goes wrong.
On the other hand, LD_PRELOAD can be easily unset by programs, and time()
hooking will not work anymore.
.PP
.SH Using libfaketime
.iX "c Symbolic links"
.PP
Once libfaketime is installed and either LD_PRELOAD or /etc/ld.so.preload has been
appropriately configured (e.g. in compile time you can define two compilation flags),
there is something else to do. The processes to be monitored must have their files
in the configuration directory (e.g. ~/.libfaketime.d/ for user-wide and
/etc/libfaketime.d/ for system-wide configuration).
.PP
Now you can put <programname>.nofake to the system configuration directory,
which prohibits users from faking time for this program (useful for mailers,
which should have a valid date and time).
.PP
In the user and system-wide configuration directory, you can put <programname>.fake
with time in seconds since 00:00:00, Jan 1, 1970. How to get a timestamp? Run
.BR date\ -d\ "31\ July\ 1983\ 5:40"\ +%s
.PP
.SH How\ it\ works
libfaketime uses a novel method for detecting and handling time(). First, this
technique intercepts all calls to library functions known to return time/date.
Then, a substituted version of the corresponding function implements the
original functionality but in a manner that ensures that only the program
not listed in *.fake files can get a valid (actual) time/date. Read sources
for more information.
.SH FILES
.HP
.I /{lib,lib64}/libfaketime.so.<version>
- main library
.HP
.I /usr/man/man8/libfaketime.8
- manual page
.HP
.I /etc/libfaketime.d/
- system-wide configuration directory,
.HP
.I ~/.libfaketime.d/
- user-wide configuration directory,
.SH "FILE FORMAT"
.I ~/.libfaketime.d/
and
.I /etc/libfaketime.d/
.P
You have to configure a separate file for each program.
.P
For example:
.P
write into the file named
.I date.fake
fixed time() value which date will always get.
.SH "SEE ALSO"
.BR libsafe (8),
.BR date (1),
.BR time (2),
.BR dlsym (3),
.BR ld.so (8),
.BR ldd (1)
.SH HISTORY
The 1st libfaketime version (1.0.0) appeared in 20 May 2002.
.SH BUGS
Report bugs using GitHub's project issues section.
.SH AUTHOR
This library was written by Krzysztof Burghardt <krzysztof@burghardt.pl>
and may be freely distributed under the terms of the GNU General Public License.
There is ABSOLUTELY NO WARRANTY for this program.