The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
module.c
Go to the documentation of this file.
1/*
2 * This program is free software; you can redistribute it and/or modify
3 * it under the terms of the GNU General Public License as published by
4 * the Free Software Foundation; either version 2 of the License, or
5 * (at your option) any later version.
6 *
7 * This program is distributed in the hope that it will be useful,
8 * but WITHOUT ANY WARRANTY; without even the implied warranty of
9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10 * GNU General Public License for more details.
11 *
12 * You should have received a copy of the GNU General Public License
13 * along with this program; if not, write to the Free Software
14 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
15 */
16
17/**
18 * $Id: 3298346cfcd4fc7950cb94d7f07f4db425f11510 $
19 *
20 * @file unlang/module.c
21 * @brief Defines functions for calling modules asynchronously
22 *
23 * @copyright 2018 The FreeRADIUS server project
24 * @copyright 2018 Arran Cudbard-Bell (a.cudbardb@freeradius.org)
25 */
26
27RCSID("$Id: 3298346cfcd4fc7950cb94d7f07f4db425f11510 $")
28
29#include <freeradius-devel/server/modpriv.h>
30#include <freeradius-devel/server/request_data.h>
31
32#include "module_priv.h"
33
34#include "tmpl.h"
35
38
39/** Push a module or submodule onto the stack for evaluation
40 *
41 * @param[out] p_result Where to write the result of calling the module.
42 * @param[in] request The current request.
43 * @param[in] mi Instance of the module to call.
44 * @param[in] method to call.
45 * @param[in] top_frame Set to UNLANG_TOP_FRAME if the interpreter should return.
46 * Set to UNLANG_SUB_FRAME if the interprer should continue.
47 * @return
48 * - 0 on success.
49 * - -1 on failure.
50 */
52 module_instance_t *mi, module_method_t method, bool top_frame)
53{
54 unlang_stack_t *stack = request->stack;
58
59 /*
60 * We need to have a unlang_module_t to push on the
61 * stack. The only sane way to do it is to attach it to
62 * the frame state.
63 */
64 MEM(mc = talloc(stack, unlang_module_t)); /* Still gets allocated from the stack pool */
65 *mc = (unlang_module_t){
66 .self = {
68 .name = mi->name,
69 .debug_name = mi->name,
70 .actions = {
71 .actions = {
73 [RLM_MODULE_FAIL] = MOD_ACTION_RETURN, /* Exit out of nested levels */
74 [RLM_MODULE_OK] = 0,
79 [RLM_MODULE_NOOP] = 0,
81 [RLM_MODULE_TIMEOUT] = MOD_ACTION_RETURN, /* Exit out of nested levels */
82 },
83 .retry = RETRY_INIT,
84 },
85 },
86 .mmc = {
87 .mi = mi,
88 .mmb = {
89 .method = method
90 }
91 }
92 };
93
94 /*
95 * Push a new module frame onto the stack
96 */
98 RLM_MODULE_NOT_SET, UNLANG_NEXT_STOP, top_frame) < 0) {
99 return -1;
100 }
101
102 frame = &stack->frame[stack->depth];
103 state = frame->state;
105 .p_result = p_result,
106 .thread = module_thread(mi)
107 };
108
109 /*
110 * Bind the temporary unlang_module_t to the frame state.
111 *
112 * There aren't _that_ many children in the stack context.
113 * so we should be ok.
114 *
115 * Hopefully in future versions of talloc the O(n) problem
116 * will be fixed for stealing.
117 */
118 talloc_steal(state, mc);
119
120 return 0;
121}
122
123/** Change the resume function of a module.
124 *
125 * @param[in] request The current request.
126 * @param[in] resume function to call when the XLAT expansion is complete.
127 * @return
128 * - <0 on error
129 * - 0 on success
130 */
132{
133 unlang_stack_t *stack = request->stack;
134 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
136
137 /*
138 * Can't resume if it isn't yielded.
139 */
140 if (!is_yielded(frame)) return -1;
141
142 /*
143 * It must be yielded in a module.
144 */
145 if (frame->instruction->type != UNLANG_TYPE_MODULE) return -1;
146
147 state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
148 state->resume = resume;
149
150 return 0;
151}
152
153/** Push a pre-compiled xlat and resumption state onto the stack for evaluation
154 *
155 * In order to use the async unlang processor the calling module needs to establish
156 * a resumption point, as the call to an xlat function may require yielding control
157 * back to the interpreter.
158 *
159 * To simplify the calling conventions, this function is provided to first push a
160 * resumption stack frame for the module, and then push an xlat stack frame.
161 *
162 * After pushing those frames the function updates the stack pointer to jump over
163 * the resumption frame and execute the xlat interpreter.
164 *
165 * When the xlat interpreter finishes, and pops the xlat frame, the unlang interpreter
166 * will then call the module resumption frame, allowing the module to continue execution.
167 *
168 * @param[in] ctx To allocate talloc value boxes and values in.
169 * @param[out] p_success Whether xlat evaluation was successful.
170 * @param[out] out Where to write the result of the expansion.
171 * @param[in] request The current request.
172 * @param[in] exp XLAT expansion to evaluate.
173 * @param[in] resume function to call when the XLAT expansion is complete.
174 * @param[in] signal function to call if a signal is received.
175 * @param[in] sigmask Signals to block.
176 * @param[in] rctx to pass to the resume() and signal() callbacks.
177 * @return
178 * - UNLANG_ACTION_PUSHED_CHILD
179 */
180unlang_action_t unlang_module_yield_to_xlat(TALLOC_CTX *ctx, bool *p_success, fr_value_box_list_t *out,
181 request_t *request, xlat_exp_head_t const *exp,
182 module_method_t resume,
183 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
184{
185 /*
186 * Push the resumption point BEFORE pushing the xlat onto
187 * the parents stack.
188 */
189 (void) unlang_module_yield(request, resume, signal, sigmask, rctx);
190
191 /*
192 * Push the xlat function
193 */
194 if (unlang_xlat_push(ctx, p_success, out, request, exp, false) < 0) return UNLANG_ACTION_STOP_PROCESSING;
195
197}
198
199/** Push a pre-compiled tmpl and resumption state onto the stack for evaluation
200 *
201 * In order to use the async unlang processor the calling module needs to establish
202 * a resumption point, as the call to an xlat function may require yielding control
203 * back to the interpreter.
204 *
205 * To simplify the calling conventions, this function is provided to first push a
206 * resumption stack frame for the module, and then push a tmpl stack frame.
207 *
208 * After pushing those frames the function updates the stack pointer to jump over
209 * the resumption frame and execute the tmpl expansion.
210 *
211 * When the tmpl interpreter finishes, and pops the tmpl frame, the unlang interpreter
212 * will then call the module resumption frame, allowing the module to continue execution.
213 *
214 * @param[in] ctx To allocate talloc value boxes and values in.
215 * @param[out] out Where to write the result of the expansion.
216 * @param[in] request The current request.
217 * @param[in] vpt the tmpl to expand
218 * @param[in] args Arguments which control how to evaluate the various
219 * types of xlats.
220 * @param[in] resume function to call when the XLAT expansion is complete.
221 * @param[in] signal function to call if a signal is received.
222 * @param[in] sigmask Signals to block.
223 * @param[in] rctx to pass to the resume() and signal() callbacks.
224 * @return
225 * - UNLANG_ACTION_PUSHED_CHILD
226 */
227unlang_action_t unlang_module_yield_to_tmpl(TALLOC_CTX *ctx, fr_value_box_list_t *out,
228 request_t *request, tmpl_t const *vpt,
230 module_method_t resume,
231 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
232{
233 /*
234 * Push the resumption point BEFORE pushing the xlat onto
235 * the parents stack.
236 */
237 (void) unlang_module_yield(request, resume, signal, sigmask, rctx);
238
239 /*
240 * Push the xlat function
241 */
242 if (unlang_tmpl_push(ctx, out, request, vpt, args) < 0) return UNLANG_ACTION_FAIL;
243
245}
246
248 request_t *request, CONF_SECTION *subcs,
249 rlm_rcode_t default_rcode,
250 module_method_t resume,
251 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
252{
253 if (!subcs) {
254 unlang_stack_t *stack = request->stack;
255 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
258
261
262 /*
263 * Be transparent to the resume function.
264 * frame->result will be overwritten
265 * anyway when we return.
266 */
267 stack->result = frame->result = default_rcode;
268 state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
269
270 return resume(p_result,
272 state->env_data, rctx),
273 request);
274 }
275
276 /*
277 * Push the resumption point BEFORE adding the subsection
278 * to the parents stack.
279 */
280 (void) unlang_module_yield(request, resume, signal, sigmask, rctx);
281
282 if (unlang_interpret_push_section(request, subcs,
283 default_rcode, UNLANG_SUB_FRAME) < 0) return UNLANG_ACTION_STOP_PROCESSING;
284
286}
287
288/** Run the retry handler. Called from an async signal handler.
289 *
290 */
292{
293 unlang_stack_t *stack = request->stack;
294 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
295 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
296
297 if (!state->retry_cb) return;
298
299 /*
300 * Assert that we have the right things. Note that this function should only be called when the
301 * retry is being used as an expiry time, i.e. mrc==1. If the module has its own retry handlers,
302 * then this function must not be called.
303 */
304 fr_assert(state->retry.config != NULL);
305 fr_assert(state->retry.config->mrc == 1);
306 fr_assert(state->rctx == mctx->rctx);
307 fr_assert(state->request == request);
308
309 /*
310 * Update the time as to when the retry is being called. This is the main purpose of the
311 * function.
312 */
313 state->retry.updated = fr_time();
314
315 state->retry_cb(mctx, request, &state->retry);
316
317}
318
319/** Cancel the retry timer on resume
320 *
321 */
323{
324 unlang_stack_t *stack = request->stack;
325 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
326 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
327
328 /*
329 * Cancel the timers, and clean up any associated retry configuration.
330 */
331 talloc_const_free(state->ev);
332 state->ev = NULL;
333 state->retry_cb = NULL;
334 state->retry.config = NULL;
335
336 return state->retry_resume(p_result, mctx, request);
337}
338
339/** Yield a request back to the interpreter, with retries
340 *
341 * This passes control of the request back to the unlang interpreter, setting
342 * callbacks to execute when the request is 'signalled' asynchronously, or when
343 * the retry timer hits.
344 *
345 * @note The module function which calls #unlang_module_yield_to_retry should return control
346 * of the C stack to the unlang interpreter immediately after calling #unlang_module_yield_to_retry.
347 * A common pattern is to use ``return unlang_module_yield_to_retry(...)``.
348 *
349 * @param[in] request The current request.
350 * @param[in] resume Called on unlang_interpret_mark_runnable().
351 * @param[in] retry Called on when a retry timer hits
352 * @param[in] signal Called on unlang_action().
353 * @param[in] sigmask Set of signals to block.
354 * @param[in] rctx to pass to the callbacks.
355 * @param[in] retry_cfg to set up the retries
356 * @return
357 * - UNLANG_ACTION_YIELD on success
358 * - UNLANG_ACTION_FAIL on failure
359 */
361 unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx,
362 fr_retry_config_t const *retry_cfg)
363{
364 unlang_stack_t *stack = request->stack;
365 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
367 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
368
369 fr_assert(stack->depth > 0);
372
373 fr_assert(!state->retry_cb);
374
375 state->retry_cb = retry;
376 state->retry_resume = resume; // so that we can cancel the retry timer
377 state->rctx = rctx;
378
379 state->request = request;
380 state->mi = m->mmc.mi;
381
382 /*
383 * Allow unlang statements to override the module configuration. i.e. if we already have a
384 * timer from unlang, then just use that.
385 */
386 if (!state->retry.config) {
387 fr_retry_init(&state->retry, fr_time(), retry_cfg);
388
389 if (fr_timer_at(state, unlang_interpret_event_list(request)->tl, &state->ev,
390 state->retry.next,
391 false, unlang_module_event_retry_handler, request) < 0) {
392 RPEDEBUG("Failed inserting event");
393 return UNLANG_ACTION_FAIL;
394 }
395 }
396
397 return unlang_module_yield(request, unlang_module_retry_resume, signal, sigmask, rctx);
398}
399
400
401/** Yield a request back to the interpreter from within a module
402 *
403 * This passes control of the request back to the unlang interpreter, setting
404 * callbacks to execute when the request is 'signalled' asynchronously, or whatever
405 * timer or I/O event the module was waiting for occurs.
406 *
407 * @note The module function which calls #unlang_module_yield should return control
408 * of the C stack to the unlang interpreter immediately after calling #unlang_module_yield.
409 * A common pattern is to use ``return unlang_module_yield(...)``.
410 *
411 * @param[in] request The current request.
412 * @param[in] resume Called on unlang_interpret_mark_runnable().
413 * @param[in] signal Called on unlang_action().
414 * @param[in] sigmask Set of signals to block.
415 * @param[in] rctx to pass to the callbacks.
416 * @return
417 * - UNLANG_ACTION_YIELD.
418 */
420 module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
421{
422 unlang_stack_t *stack = request->stack;
423 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
424 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
425
426 REQUEST_VERIFY(request); /* Check the yielded request is sane */
427
428 state->rctx = rctx;
429 state->resume = resume;
430
431#ifndef NDEBUG
432 /*
433 * We can't do asynchronous signals if the module is not thread safe.
434 *
435 * Right now, none of the modules marked THREAD_UNSAFE call yield, or set signal callbacks.
436 * Which means that this code doesn't affect anything.
437 *
438 * At some point if we do have modules which take signals and which are not thread safe, then
439 * those modules have to ensure that their signal handlers do any locking necessary.
440 */
441 if (signal) {
443
445 fr_assert(m);
446
448 }
449#endif
450
451 state->signal = signal;
452 state->sigmask = sigmask;
453
454 /*
455 * We set the repeatable flag here,
456 * so that the resume function is always
457 * called going back up the stack.
458 */
460
461 return UNLANG_ACTION_YIELD;
462}
463
464/*
465 * Lock the mutex for the module
466 */
467static inline CC_HINT(always_inline) void safe_lock(module_instance_t *mi)
468{
469 if ((mi->exported->flags & MODULE_TYPE_THREAD_UNSAFE) != 0) pthread_mutex_lock(&mi->mutex);
470}
471
472/*
473 * Unlock the mutex for the module
474 */
475static inline CC_HINT(always_inline) void safe_unlock(module_instance_t *mi)
476{
477 if ((mi->exported->flags & MODULE_TYPE_THREAD_UNSAFE) != 0) pthread_mutex_unlock(&mi->mutex);
478}
479
480/** Send a signal (usually stop) to a request
481 *
482 * This is typically called via an "async" action, i.e. an action
483 * outside of the normal processing of the request.
484 *
485 * If there is no #unlang_module_signal_t callback defined, the action is ignored.
486 *
487 * @param[in] request The current request.
488 * @param[in] frame current stack frame.
489 * @param[in] action to signal.
490 */
492{
493 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
495 char const *caller;
496
497 if (!state->signal) return;
498
499 if (action == FR_SIGNAL_CANCEL) {
500 /*
501 * Cancel the retry timer, if it is set.
502 *
503 * Because cancellation functions and actual unwinding are done separately
504 * the retry timer can fire after the module has been cancelled.
505 */
506 TALLOC_FREE(state->ev);
507 }
508
509 /*
510 * Async calls can't push anything onto the unlang stack, so we just use a local "caller" here.
511 */
512 caller = request->module;
513 request->module = m->mmc.mi->name;
514
515 /*
516 * Call the signal routines. Note that signals are
517 * explicitely asynchronous, even if the module has
518 * declared itself to be MODULE_TYPE_THREAD_UNSAFE.
519 */
520 if (!(action & state->sigmask)) state->signal(MODULE_CTX(m->mmc.mi, state->thread->data, state->env_data, state->rctx), request, action);
521
522 if (action == FR_SIGNAL_CANCEL) {
523 /*
524 * One fewer caller for this module. Since this module
525 * has been cancelled, decrement the active callers and
526 * ignore any future signals.
527 */
528 state->thread->active_callers--;
529 state->signal = NULL;
530 }
531
532 request->module = caller;
533
534}
535
536/** Cleanup after a module completes
537 *
538 */
540{
541 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
542 rlm_rcode_t rcode = state->rcode_set ? state->rcode : *p_result;
543
544#ifndef NDEBUG
545 fr_assert(state->unlang_indent == request->log.indent.unlang);
546#endif
547
550
551 RDEBUG("%s (%s)", frame->instruction->name ? frame->instruction->name : "",
552 fr_table_str_by_value(mod_rcode_table, rcode, "<invalid>"));
553
554 if (state->p_result) *state->p_result = rcode; /* Inform our caller if we have one */
555 *p_result = rcode;
556 request->module = state->previous_module;
557
559}
560
561/** Cleanup after a yielded module completes
562 *
563 */
565{
566 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
567
568 state->thread->active_callers--;
569
570 return unlang_module_done(p_result, request, frame);
571}
572
573/** Wrapper to call a module's resumption function
574 *
575 * This is called _after_ the module first yields, and again after any
576 * other yields.
577 */
579{
580 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
582 module_method_t resume;
584
585 /*
586 * Update the rcode from any child calls that
587 * may have been performed. The module still
588 * has a chance to override this rcode if it
589 * wants, but process modules in particular
590 * expect to see the result of child
591 * evaluations available to them in p_result.
592 */
593 state->rcode = *p_result < RLM_MODULE_NUMCODES ? *p_result : RLM_MODULE_NOOP;
594
595 fr_assert(state->resume != NULL);
596
597 resume = state->resume;
598
599 /*
600 * The module *MUST* explicitly set the resume
601 * function when yielding or pushing children
602 * if it wants to be called again later.
603 */
604 state->resume = NULL;
605
606 /*
607 * Lock is noop unless instance->mutex is set.
608 */
609 safe_lock(m->mmc.mi);
610 ua = resume(&state->rcode, MODULE_CTX(m->mmc.mi, state->thread->data,
611 state->env_data, state->rctx), request);
612 safe_unlock(m->mmc.mi);
613
614 if (request->master_state == REQUEST_STOP_PROCESSING) ua = UNLANG_ACTION_STOP_PROCESSING;
615
616 switch (ua) {
618 RWARN("Module %s or worker signalled to stop processing request", m->mmc.mi->name);
619 if (state->p_result) *state->p_result = state->rcode;
620 state->thread->active_callers--;
621 *p_result = state->rcode;
622 request->module = state->previous_module;
624
626 /*
627 * The module yielded but didn't set a
628 * resume function, this means it's done
629 * and when the I/O operation completes
630 * it shouldn't be called again.
631 */
632 if (!state->resume) {
634 } else {
635 repeatable_set(frame);
636 }
637 return UNLANG_ACTION_YIELD;
638
639 /*
640 * The module is done (for now).
641 * But, running it pushed one or more asynchronous
642 * calls onto the stack for evaluation.
643 * These need to be run before the module resumes
644 * or the next unlang instruction is processed.
645 */
647 /*
648 * The module pushed a child and didn't
649 * set a resume function, this means
650 * it's done, and we won't call it again
651 * but we still need to do some cleanup
652 * after the child returns.
653 */
654 if (!state->resume) {
656 state->rcode_set = false; /* Preserve the child rcode */
657 } else {
658 repeatable_set(frame);
659 }
661
663 /*
664 * Module set a resume function but
665 * didn't yield or push additional
666 * children.
667 *
668 * Evaluate the function now and
669 * use the result as the final result.
670 */
671 if (state->resume) return unlang_module_resume(p_result, request, frame);
672 request->module = state->previous_module;
673 break;
674
676 *p_result = RLM_MODULE_FAIL;
677 request->module = state->previous_module;
678 break;
679
680 case UNLANG_ACTION_EXECUTE_NEXT: /* Not valid */
681 fr_assert(0);
682 *p_result = RLM_MODULE_FAIL;
683 break;
684 }
685
686 unlang_module_resume_done(p_result, request, frame);
687 request->module = state->previous_module;
688
689 return ua;
690}
691
692/** Call the callback registered for a retry event
693 *
694 * @param[in] tl the event timer was inserted into.
695 * @param[in] now The current time, as held by the event_list.
696 * @param[in] ctx the stack frame
697 *
698 */
700{
701 request_t *request = talloc_get_type_abort(ctx, request_t);
702 unlang_stack_t *stack = request->stack;
703 unlang_stack_frame_t *frame = &stack->frame[stack->depth];
704 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
705
706 switch (fr_retry_next(&state->retry, now)) {
708 if (state->retry_cb) {
709 /*
710 * Call the module retry handler, with the state of the retry. On MRD / MRC, the
711 * module is made runnable again, and the "resume" function is called.
712 */
713 state->retry_cb(MODULE_CTX(state->mi, state->thread, state->env_data, state->rctx), state->request, &state->retry);
714 } else {
715 /*
716 * For signals, the module will get either a RETRY
717 * signal, or a TIMEOUT signal (also for max count).
718 *
719 * The signal handler should generally change the resume
720 * function, and mark the request as runnable. We
721 * probably don't want the module to do tons of work in
722 * the signal handler, as it's called from the event
723 * loop. And doing so could affect the other event
724 * timers.
725 *
726 * Note also that we call frame->signal(), and not
727 * unlang_interpret_signal(). That is because we want to
728 * signal only the module. We know that the other frames
729 * on the stack can't handle this particular signal. So
730 * there's no point in calling them. Or, if sections
731 * have their own retry handlers, then we don't want to
732 * signal those _other_ retry handlers with _our_ signal.
733 */
734 frame->signal(request, frame, FR_SIGNAL_RETRY);
735 }
736
737 /*
738 * Reset the timer.
739 */
740 if (fr_timer_at(state, unlang_interpret_event_list(request)->tl, &state->ev, state->retry.next,
741 false, unlang_module_event_retry_handler, request) < 0) {
742 RPEDEBUG("Failed inserting event");
743 unlang_interpret_mark_runnable(request); /* and let the caller figure out what's up */
744 }
745 return;
746
747 case FR_RETRY_MRD:
748 RDEBUG("Reached max_rtx_duration (%pVs > %pVs) - sending timeout",
750 break;
751
752 case FR_RETRY_MRC:
753 RDEBUG("Reached max_rtx_count %u- sending timeout",
754 state->retry.config->mrc);
755 break;
756 }
757
758 /*
759 * Run the retry handler on MRD / MRC, too.
760 */
761 if (state->retry_cb) {
762 state->retry_cb(MODULE_CTX(state->mi, state->thread, state->env_data, state->rctx), state->request, &state->retry);
763 } else {
764 frame->signal(request, frame, FR_SIGNAL_TIMEOUT);
765 }
766
767 /*
768 * On final timeout, always mark the request as runnable.
769 */
771}
772
774{
776 unlang_frame_state_module_t *state = talloc_get_type_abort(frame->state, unlang_frame_state_module_t);
778 fr_time_t now = fr_time_wrap(0);
779
780 *p_result = state->rcode = RLM_MODULE_NOOP;
781 state->rcode_set = true;
782 state->previous_module = request->module;
783
784#ifndef NDEBUG
785 state->unlang_indent = request->log.indent.unlang;
786#endif
787 /*
788 * Process a stand-alone child, and fall through
789 * to dealing with it's parent.
790 */
792 fr_assert(m);
793
794 RDEBUG4("[%i] %s - %s (%s)", stack_depth_current(request), __FUNCTION__,
795 m->mmc.mi->module->exported->name, m->mmc.mi->name);
796
797 state->p_result = NULL;
798
799 /*
800 * Return administratively configured return code
801 */
802 if (m->mmc.mi->force) {
803 state->rcode = m->mmc.mi->code;
805 goto done;
806 }
807
808 if (m->mmc.mmb.method_env) {
809 if (!state->env_data) {
810 ua = call_env_expand(state, request, &state->env_result, &state->env_data, m->call_env);
811 switch (ua) {
813 goto fail;
814
818
819 default:
820 break;
821 }
822 }
823
824 /*
825 * Fail the module call on callenv failure
826 */
828 }
829
830 /*
831 * Grab the thread/module specific data if any exists.
832 */
833 state->thread = module_thread(m->mmc.mi);
834 fr_assert(state->thread != NULL);
835
836 /*
837 * For logging unresponsive children.
838 */
839 state->thread->total_calls++;
840
841 /*
842 * If we're doing retries, remember when we started
843 * running the module.
844 */
846
847 request->module = m->mmc.mi->name;
848 safe_lock(m->mmc.mi); /* Noop unless instance->mutex set */
849 ua = m->mmc.mmb.method(&state->rcode,
850 MODULE_CTX(m->mmc.mi, state->thread->data, state->env_data, NULL),
851 request);
852 safe_unlock(m->mmc.mi);
853
854 if (request->master_state == REQUEST_STOP_PROCESSING) ua = UNLANG_ACTION_STOP_PROCESSING;
855
856 switch (ua) {
857 /*
858 * It is now marked as "stop" when it wasn't before, we
859 * must have been blocked.
860 */
862 RWARN("Module %s became unblocked", m->mmc.mi->name);
863 if (state->p_result) *state->p_result = state->rcode;
864 *p_result = state->rcode;
865 request->module = state->previous_module;
867
869 state->thread->active_callers++;
870
871 /*
872 * The module yielded but didn't set a
873 * resume function, this means it's done
874 * and when the I/O operation completes
875 * it shouldn't be called again.
876 */
877 if (!state->resume) {
879 } else {
881 }
882
883 /*
884 * If we have retry timers, then start the retries.
885 */
888
889 fr_retry_init(&state->retry, now, &frame->instruction->actions.retry);
890
891 if (fr_timer_at(state, unlang_interpret_event_list(request)->tl,
892 &state->ev, state->retry.next,
893 false, unlang_module_event_retry_handler, request) < 0) {
894 RPEDEBUG("Failed inserting event");
895 goto fail;
896 }
897 }
898
899 return UNLANG_ACTION_YIELD;
900
901 /*
902 * The module is done (for now).
903 * But, running it pushed one or more asynchronous
904 * calls onto the stack for evaluation.
905 * These need to be run before the module resumes
906 * or the next unlang instruction is processed.
907 */
909 /*
910 * The module pushed a child and didn't
911 * set a resume function, this means
912 * it's done, and we won't call it again
913 * but we still need to do some cleanup
914 * after the child returns.
915 */
916 if (!state->resume) {
918 state->rcode_set = false; /* Preserve the child rcode */
919 } else {
920 repeatable_set(frame);
921 }
923
925 /*
926 * Module set a resume function but
927 * didn't yield or push additional
928 * children.
929 *
930 * Evaluate the function now and
931 * use the result as the final result.
932 */
933 if (state->resume) {
934 frame->process = unlang_module_resume; /* unlang_module_resume will assume this is set */
935 return unlang_module_resume(p_result, request, frame);
936 }
937 break;
938
940 fail:
941 *p_result = RLM_MODULE_FAIL;
942 break;
943
945 fr_assert(0);
946 *p_result = RLM_MODULE_FAIL;
947 break;
948 }
949
950done:
951 request->module = state->previous_module;
952 unlang_module_done(p_result, request, frame);
953 return ua;
954}
955
957{
959 &(unlang_op_t){
960 .name = "module",
961 .interpret = unlang_module,
963 .signal = unlang_module_signal,
964 .frame_state_size = sizeof(unlang_frame_state_module_t),
965 .frame_state_type = "unlang_frame_state_module_t",
966 });
967}
unlang_action_t
Returned by unlang_op_t calls, determine the next action of the interpreter.
Definition action.h:35
@ UNLANG_ACTION_PUSHED_CHILD
unlang_t pushed a new child onto the stack, execute it instead of continuing.
Definition action.h:39
@ UNLANG_ACTION_EXECUTE_NEXT
Execute the next unlang_t.
Definition action.h:38
@ UNLANG_ACTION_STOP_PROCESSING
Break out of processing the current request (unwind).
Definition action.h:42
@ UNLANG_ACTION_FAIL
Encountered an unexpected error.
Definition action.h:36
@ UNLANG_ACTION_CALCULATE_RESULT
Calculate a new section rlm_rcode_t value.
Definition action.h:37
@ UNLANG_ACTION_YIELD
Temporarily pause execution until an event occurs.
Definition action.h:41
va_list args
Definition acutest.h:770
#define RCSID(id)
Definition build.h:485
#define UNUSED
Definition build.h:317
unlang_action_t call_env_expand(TALLOC_CTX *ctx, request_t *request, call_env_result_t *env_result, void **env_data, call_env_t const *call_env)
Initialise the expansion of a call environment.
Definition call_env.c:294
@ CALL_ENV_SUCCESS
Definition call_env.h:52
A section grouping multiple CONF_PAIR.
Definition cf_priv.h:101
fr_table_num_sorted_t const mod_rcode_table[]
Definition compile.c:78
#define MEM(x)
Definition debug.h:36
void unlang_interpret_mark_runnable(request_t *request)
Mark a request as resumable.
Definition interpret.c:1357
int unlang_interpret_push(request_t *request, unlang_t const *instruction, rlm_rcode_t default_rcode, bool do_next_sibling, bool top_frame)
Push a new frame onto the stack.
Definition interpret.c:141
int unlang_interpret_push_section(request_t *request, CONF_SECTION *cs, rlm_rcode_t default_rcode, bool top_frame)
Push a configuration section onto the request stack for later interpretation.
Definition interpret.c:926
fr_event_list_t * unlang_interpret_event_list(request_t *request)
Get the event list for the current interpreter.
Definition interpret.c:1754
#define UNLANG_SUB_FRAME
Definition interpret.h:36
#define RWARN(fmt,...)
Definition log.h:297
#define RPEDEBUG(fmt,...)
Definition log.h:376
#define RDEBUG4(fmt,...)
Definition log.h:344
void unlang_register(int type, unlang_op_t *op)
Register an operation with the interpreter.
Definition base.c:63
static char * stack[MAX_STACK]
Definition radmin.c:158
@ MOD_ACTION_RETURN
Definition mod_action.h:40
fr_retry_config_t retry
Definition mod_action.h:63
void * rctx
Resume ctx that a module previously set.
Definition module_ctx.h:45
#define MODULE_CTX(_mi, _thread, _env_data, _rctx)
Wrapper to create a module_ctx_t as a compound literal.
Definition module_ctx.h:128
Temporary structure to hold arguments for module calls.
Definition module_ctx.h:41
Declarations for the unlang module interface.
fr_timer_t * ev
retry timer just for this module.
Definition module_priv.h:87
rlm_rcode_t rcode
the result, only for unlang_module_resume_final.
Definition module_priv.h:63
static unlang_t * unlang_module_to_generic(unlang_module_t *p)
static unlang_module_t * unlang_generic_to_module(unlang_t const *p)
Definition module_priv.h:94
module_instance_t const * mi
Module instance to pass to callbacks.
Definition module_priv.h:84
module_method_t resume
resumption handler
Definition module_priv.h:72
char const * previous_module
old request->module
Definition module_priv.h:46
fr_signal_t sigmask
Signals to block.
Definition module_priv.h:74
module_method_t retry_resume
which stops retries on resume
Definition module_priv.h:81
bool rcode_set
Overwrite the current rcode for the section with the module rcode.
Definition module_priv.h:64
call_env_result_t env_result
Result of the previous call environment expansion.
Definition module_priv.h:52
module_method_call_t mmc
Everything needed to call a module method.
Definition module_priv.h:38
fr_retry_t retry
retry timers, etc.
Definition module_priv.h:88
void * env_data
Expanded per call "call environment" tmpls.
Definition module_priv.h:53
rlm_rcode_t * p_result
Where to store the result.
Definition module_priv.h:62
module_thread_instance_t * thread
thread-local data for this module.
Definition module_priv.h:47
unlang_t self
Common fields in all unlang_t tree nodes.
Definition module_priv.h:36
unlang_module_signal_t signal
for signal handlers
Definition module_priv.h:73
int unlang_indent
Record what this was when we entered the module.
Definition module_priv.h:56
void * rctx
for resume / signal
Definition module_priv.h:71
call_env_t const * call_env
The per call parsed call environment.
Definition module_priv.h:37
unlang_module_retry_t retry_cb
callback to run on timeout
Definition module_priv.h:82
A module stack entry.
Definition module_priv.h:45
A call to a module method.
Definition module_priv.h:35
module_instance_t * mi
The process modules also push module calls onto the stack for execution.
Definition module_rlm.h:63
module_method_binding_t mmb
Method we're calling.
Definition module_rlm.h:70
#define fr_assert(_expr)
Definition rad_assert.h:38
static bool done
Definition radclient.c:81
#define RDEBUG(fmt,...)
Definition radclient.h:53
#define RETURN_MODULE_FAIL
Definition rcode.h:57
rlm_rcode_t
Return codes indicating the result of the module call.
Definition rcode.h:40
@ RLM_MODULE_INVALID
The module considers the request invalid.
Definition rcode.h:45
@ RLM_MODULE_OK
The module is OK, continue.
Definition rcode.h:43
@ RLM_MODULE_FAIL
Module failed, don't reply.
Definition rcode.h:42
@ RLM_MODULE_DISALLOW
Reject the request (user is locked out).
Definition rcode.h:46
@ RLM_MODULE_REJECT
Immediately reject the request.
Definition rcode.h:41
@ RLM_MODULE_TIMEOUT
Module (or section) timed out.
Definition rcode.h:50
@ RLM_MODULE_NOTFOUND
User not found.
Definition rcode.h:47
@ RLM_MODULE_UPDATED
OK (pairs modified).
Definition rcode.h:49
@ RLM_MODULE_NOT_SET
Error resolving rcode (should not be returned by modules).
Definition rcode.h:52
@ RLM_MODULE_NOOP
Module succeeded without doing anything.
Definition rcode.h:48
@ RLM_MODULE_NUMCODES
How many valid return codes there are.
Definition rcode.h:51
@ RLM_MODULE_HANDLED
The module handled the request, so stop.
Definition rcode.h:44
#define REQUEST_VERIFY(_x)
Definition request.h:305
@ REQUEST_STOP_PROCESSING
Request has been signalled to stop.
Definition request.h:88
char const * name
Instance name e.g. user_database.
Definition module.h:336
@ MODULE_TYPE_THREAD_UNSAFE
Module is not threadsafe.
Definition module.h:48
module_flags_t flags
Flags that control how a module starts up and how a module is called.
Definition module.h:228
uint64_t active_callers
total number of times we've been called
Definition module.h:360
bool force
Force the module to return a specific code.
Definition module.h:298
module_method_t method
Module method to call.
Definition module.h:176
void * data
Thread specific instance data.
Definition module.h:353
rlm_rcode_t code
Code module will return when 'force' has has been set to true.
Definition module.h:301
call_env_method_t const * method_env
Method specific call_env.
Definition module.h:177
static module_thread_instance_t * module_thread(module_instance_t const *mi)
Retrieve module/thread specific instance for a module.
Definition module.h:482
unlang_action_t(* module_method_t)(rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
Module section callback.
Definition module.h:68
module_t * exported
Public module structure.
Definition module.h:277
pthread_mutex_t mutex
Used prevent multiple threads entering a thread unsafe module simultaneously.
Definition module.h:284
Module instance data.
Definition module.h:266
static fr_slen_t vpt
Definition tmpl.h:1269
fr_signal_t
Signals that can be generated/processed by request signal handlers.
Definition signal.h:38
@ FR_SIGNAL_RETRY
a retry timer has hit
Definition signal.h:46
@ FR_SIGNAL_TIMEOUT
a retry timeout or max count has hit
Definition signal.h:47
@ FR_SIGNAL_CANCEL
Request has been cancelled.
Definition signal.h:40
unlang_action_t unlang_module_yield_to_section(rlm_rcode_t *p_result, request_t *request, CONF_SECTION *subcs, rlm_rcode_t default_rcode, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Definition module.c:247
int unlang_module_set_resume(request_t *request, module_method_t resume)
Change the resume function of a module.
Definition module.c:131
static unlang_action_t unlang_module(rlm_rcode_t *p_result, request_t *request, unlang_stack_frame_t *frame)
Definition module.c:773
unlang_action_t unlang_module_yield_to_xlat(TALLOC_CTX *ctx, bool *p_success, fr_value_box_list_t *out, request_t *request, xlat_exp_head_t const *exp, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Push a pre-compiled xlat and resumption state onto the stack for evaluation.
Definition module.c:180
static void safe_lock(module_instance_t *mi)
Definition module.c:467
static void unlang_module_event_retry_handler(UNUSED fr_timer_list_t *tl, fr_time_t now, void *ctx)
Call the callback registered for a retry event.
Definition module.c:699
int unlang_module_push(rlm_rcode_t *p_result, request_t *request, module_instance_t *mi, module_method_t method, bool top_frame)
Push a module or submodule onto the stack for evaluation.
Definition module.c:51
unlang_action_t unlang_module_yield(request_t *request, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Yield a request back to the interpreter from within a module.
Definition module.c:419
unlang_action_t unlang_module_yield_to_retry(request_t *request, module_method_t resume, unlang_module_retry_t retry, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx, fr_retry_config_t const *retry_cfg)
Yield a request back to the interpreter, with retries.
Definition module.c:360
void unlang_module_init(void)
Definition module.c:956
static unlang_action_t unlang_module_resume(rlm_rcode_t *p_result, request_t *request, unlang_stack_frame_t *frame)
Wrapper to call a module's resumption function.
Definition module.c:578
static unlang_action_t unlang_module_resume_done(rlm_rcode_t *p_result, request_t *request, unlang_stack_frame_t *frame)
Cleanup after a yielded module completes.
Definition module.c:564
static unlang_action_t unlang_module_done(rlm_rcode_t *p_result, request_t *request, unlang_stack_frame_t *frame)
Cleanup after a module completes.
Definition module.c:539
void unlang_module_retry_now(module_ctx_t const *mctx, request_t *request)
Run the retry handler.
Definition module.c:291
unlang_action_t unlang_module_yield_to_tmpl(TALLOC_CTX *ctx, fr_value_box_list_t *out, request_t *request, tmpl_t const *vpt, unlang_tmpl_args_t *args, module_method_t resume, unlang_module_signal_t signal, fr_signal_t sigmask, void *rctx)
Push a pre-compiled tmpl and resumption state onto the stack for evaluation.
Definition module.c:227
static void safe_unlock(module_instance_t *mi)
Definition module.c:475
static void unlang_module_signal(request_t *request, unlang_stack_frame_t *frame, fr_signal_t action)
Send a signal (usually stop) to a request.
Definition module.c:491
static unlang_action_t unlang_module_retry_resume(rlm_rcode_t *p_result, module_ctx_t const *mctx, request_t *request)
Cancel the retry timer on resume.
Definition module.c:322
#define fr_time()
Allow us to arbitrarily manipulate time.
Definition state_test.c:8
#define fr_table_str_by_value(_table, _number, _def)
Convert an integer to a string.
Definition table.h:772
static int talloc_const_free(void const *ptr)
Free const'd memory.
Definition talloc.h:229
#define fr_time_wrap(_time)
Definition time.h:145
#define fr_time_delta_ispos(_a)
Definition time.h:290
#define fr_time_gt(_a, _b)
Definition time.h:237
#define fr_time_sub(_a, _b)
Subtract one time from another.
Definition time.h:229
"server local" time.
Definition time.h:69
An event timer list.
Definition timer.c:50
#define fr_timer_at(...)
Definition timer.h:81
int unlang_tmpl_push(TALLOC_CTX *ctx, fr_value_box_list_t *out, request_t *request, tmpl_t const *tmpl, unlang_tmpl_args_t *args)
Push a tmpl onto the stack for evaluation.
Definition tmpl.c:260
void(* unlang_module_retry_t)(module_ctx_t const *mctx, request_t *request, fr_retry_t const *retry)
A callback when a retry happens.
Definition module.h:52
void(* unlang_module_signal_t)(module_ctx_t const *mctx, request_t *request, fr_signal_t action)
A callback when the request gets a fr_signal_t.
Definition module.h:80
Functions to allow tmpls to push resumption frames onto the stack and inform the interpreter about th...
Arguments for evaluating different types of tmpls.
Definition tmpl.h:47
int unlang_xlat_push(TALLOC_CTX *ctx, bool *p_success, fr_value_box_list_t *out, request_t *request, xlat_exp_head_t const *xlat, bool top_frame)
Push a pre-compiled xlat onto the stack for evaluation.
Definition xlat.c:282
unlang_signal_t signal
function to call when signalling this stack frame
void * state
Stack frame specialisations.
unlang_mod_actions_t actions
Priorities, etc. for the various return codes.
#define UNLANG_NEXT_STOP
Definition unlang_priv.h:96
char const * name
Unknown...
static int stack_depth_current(request_t *request)
@ UNLANG_TYPE_MODULE
Module method.
Definition unlang_priv.h:46
static void frame_repeat(unlang_stack_frame_t *frame, unlang_process_t process)
Mark the current stack frame up for repeat, and set a new process function.
unlang_t const * instruction
The unlang node we're evaluating.
static bool is_yielded(unlang_stack_frame_t const *frame)
rlm_rcode_t result
The result from executing the instruction.
@ UNLANG_OP_FLAG_RETURN_POINT
Return point.
@ UNLANG_OP_FLAG_RCODE_SET
Set request->rcode to the result of this operation.
static void repeatable_set(unlang_stack_frame_t *frame)
unlang_process_t process
function to call for interpreting this stack frame
unlang_type_t type
The specialisation of this node.
An unlang operation.
Our interpreter stack, as distinct from the C stack.
An unlang stack associated with a request.
fr_retry_state_t fr_retry_next(fr_retry_t *r, fr_time_t now)
Initialize a retransmission counter.
Definition retry.c:108
void fr_retry_init(fr_retry_t *r, fr_time_t now, fr_retry_config_t const *config)
Initialize a retransmission counter.
Definition retry.c:36
fr_time_t start
when we started the retransmission
Definition retry.h:53
fr_time_delta_t irt
Initial transmission time.
Definition retry.h:33
#define RETRY_INIT
Definition retry.h:39
uint32_t mrc
Maximum retransmission count.
Definition retry.h:36
fr_retry_config_t const * config
master configuration
Definition retry.h:52
@ FR_RETRY_MRC
reached maximum retransmission count
Definition retry.h:47
@ FR_RETRY_CONTINUE
Definition retry.h:46
@ FR_RETRY_MRD
reached maximum retransmission duration
Definition retry.h:48
fr_time_delta_t mrd
Maximum retransmission duration.
Definition retry.h:35
fr_time_t updated
last update, really a cached "now".
Definition retry.h:56
fr_time_t next
when the next timer should be set
Definition retry.h:55
#define fr_box_time_delta(_val)
Definition value.h:354
static size_t char ** out
Definition value.h:1012