Fix a debug message (add a newline).
[Samba.git] / source / nsswitch / idmap.c
blob676ab6eb53a65712457e263417eb14691d0a24c5
1 /*
2 Unix SMB/CIFS implementation.
3 ID Mapping
4 Copyright (C) Tim Potter 2000
5 Copyright (C) Jim McDonough <jmcd@us.ibm.com> 2003
6 Copyright (C) Simo Sorce 2003-2007
7 Copyright (C) Jeremy Allison 2006
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 #include "includes.h"
25 #include "winbindd.h"
27 #undef DBGC_CLASS
28 #define DBGC_CLASS DBGC_IDMAP
30 static_decl_idmap;
32 struct idmap_backend {
33 const char *name;
34 struct idmap_methods *methods;
35 struct idmap_backend *prev, *next;
38 struct idmap_alloc_backend {
39 const char *name;
40 struct idmap_alloc_methods *methods;
41 struct idmap_alloc_backend *prev, *next;
44 struct idmap_cache_ctx;
46 struct idmap_alloc_context {
47 const char *params;
48 struct idmap_alloc_methods *methods;
49 BOOL initialized;
52 static TALLOC_CTX *idmap_ctx = NULL;
53 static struct idmap_cache_ctx *idmap_cache;
55 static struct idmap_backend *backends = NULL;
56 static struct idmap_domain **idmap_domains = NULL;
57 static int num_domains = 0;
58 static int pdb_dom_num = -1;
59 static int def_dom_num = -1;
61 static struct idmap_alloc_backend *alloc_backends = NULL;
62 static struct idmap_alloc_context *idmap_alloc_ctx = NULL;
64 #define IDMAP_CHECK_RET(ret) do { \
65 if ( ! NT_STATUS_IS_OK(ret)) { \
66 DEBUG(2, ("ERROR: NTSTATUS = 0x%08x\n", NT_STATUS_V(ret))); \
67 goto done; \
68 } } while(0)
69 #define IDMAP_REPORT_RET(ret) do { \
70 if ( ! NT_STATUS_IS_OK(ret)) { \
71 DEBUG(2, ("ERROR: NTSTATUS = 0x%08x\n", NT_STATUS_V(ret))); \
72 } } while(0)
73 #define IDMAP_CHECK_ALLOC(mem) do { \
74 if (!mem) { \
75 DEBUG(0, ("Out of memory!\n")); ret = NT_STATUS_NO_MEMORY; \
76 goto done; \
77 } } while(0)
79 static struct idmap_methods *get_methods(struct idmap_backend *be,
80 const char *name)
82 struct idmap_backend *b;
84 for (b = be; b; b = b->next) {
85 if (strequal(b->name, name)) {
86 return b->methods;
90 return NULL;
93 static struct idmap_alloc_methods *get_alloc_methods(
94 struct idmap_alloc_backend *be,
95 const char *name)
97 struct idmap_alloc_backend *b;
99 for (b = be; b; b = b->next) {
100 if (strequal(b->name, name)) {
101 return b->methods;
105 return NULL;
108 BOOL idmap_is_offline(void)
110 return ( lp_winbind_offline_logon() &&
111 get_global_winbindd_state_offline() );
114 /**********************************************************************
115 Allow a module to register itself as a method.
116 **********************************************************************/
118 NTSTATUS smb_register_idmap(int version, const char *name,
119 struct idmap_methods *methods)
121 struct idmap_methods *test;
122 struct idmap_backend *entry;
124 if (!idmap_ctx) {
125 return NT_STATUS_INTERNAL_DB_ERROR;
128 if ((version != SMB_IDMAP_INTERFACE_VERSION)) {
129 DEBUG(0, ("Failed to register idmap module.\n"
130 "The module was compiled against "
131 "SMB_IDMAP_INTERFACE_VERSION %d,\n"
132 "current SMB_IDMAP_INTERFACE_VERSION is %d.\n"
133 "Please recompile against the current version "
134 "of samba!\n",
135 version, SMB_IDMAP_INTERFACE_VERSION));
136 return NT_STATUS_OBJECT_TYPE_MISMATCH;
139 if (!name || !name[0] || !methods) {
140 DEBUG(0,("Called with NULL pointer or empty name!\n"));
141 return NT_STATUS_INVALID_PARAMETER;
144 test = get_methods(backends, name);
145 if (test) {
146 DEBUG(0,("Idmap module %s already registered!\n", name));
147 return NT_STATUS_OBJECT_NAME_COLLISION;
150 entry = talloc(idmap_ctx, struct idmap_backend);
151 if ( ! entry) {
152 DEBUG(0,("Out of memory!\n"));
153 return NT_STATUS_NO_MEMORY;
155 entry->name = talloc_strdup(idmap_ctx, name);
156 if ( ! entry->name) {
157 DEBUG(0,("Out of memory!\n"));
158 return NT_STATUS_NO_MEMORY;
160 entry->methods = methods;
162 DLIST_ADD(backends, entry);
163 DEBUG(5, ("Successfully added idmap backend '%s'\n", name));
164 return NT_STATUS_OK;
167 /**********************************************************************
168 Allow a module to register itself as a method.
169 **********************************************************************/
171 NTSTATUS smb_register_idmap_alloc(int version, const char *name,
172 struct idmap_alloc_methods *methods)
174 struct idmap_alloc_methods *test;
175 struct idmap_alloc_backend *entry;
177 if (!idmap_ctx) {
178 return NT_STATUS_INTERNAL_DB_ERROR;
181 if ((version != SMB_IDMAP_INTERFACE_VERSION)) {
182 DEBUG(0, ("Failed to register idmap alloc module.\n"
183 "The module was compiled against "
184 "SMB_IDMAP_INTERFACE_VERSION %d,\n"
185 "current SMB_IDMAP_INTERFACE_VERSION is %d.\n"
186 "Please recompile against the current version "
187 "of samba!\n",
188 version, SMB_IDMAP_INTERFACE_VERSION));
189 return NT_STATUS_OBJECT_TYPE_MISMATCH;
192 if (!name || !name[0] || !methods) {
193 DEBUG(0,("Called with NULL pointer or empty name!\n"));
194 return NT_STATUS_INVALID_PARAMETER;
197 test = get_alloc_methods(alloc_backends, name);
198 if (test) {
199 DEBUG(0,("idmap_alloc module %s already registered!\n", name));
200 return NT_STATUS_OBJECT_NAME_COLLISION;
203 entry = talloc(idmap_ctx, struct idmap_alloc_backend);
204 if ( ! entry) {
205 DEBUG(0,("Out of memory!\n"));
206 return NT_STATUS_NO_MEMORY;
208 entry->name = talloc_strdup(idmap_ctx, name);
209 if ( ! entry->name) {
210 DEBUG(0,("Out of memory!\n"));
211 return NT_STATUS_NO_MEMORY;
213 entry->methods = methods;
215 DLIST_ADD(alloc_backends, entry);
216 DEBUG(5, ("Successfully added idmap alloc backend '%s'\n", name));
217 return NT_STATUS_OK;
220 static int close_domain_destructor(struct idmap_domain *dom)
222 NTSTATUS ret;
224 ret = dom->methods->close_fn(dom);
225 if (!NT_STATUS_IS_OK(ret)) {
226 DEBUG(3, ("Failed to close idmap domain [%s]!\n", dom->name));
229 return 0;
232 /**************************************************************************
233 Shutdown.
234 **************************************************************************/
236 NTSTATUS idmap_close(void)
238 /* close the alloc backend first before freeing idmap_ctx */
239 if (idmap_alloc_ctx) {
240 idmap_alloc_ctx->methods->close_fn();
241 idmap_alloc_ctx->methods = NULL;
243 alloc_backends = NULL;
245 /* this talloc_free call will fire the talloc destructors
246 * that will free all active backends resources */
247 TALLOC_FREE(idmap_ctx);
248 idmap_cache = NULL;
249 idmap_domains = NULL;
250 backends = NULL;
252 return NT_STATUS_OK;
255 /****************************************************************************
256 ****************************************************************************/
258 NTSTATUS idmap_init_cache(void)
260 /* Always initialize the cache. We'll have to delay initialization
261 of backends if we are offline */
263 if ( idmap_ctx ) {
264 return NT_STATUS_OK;
267 if ( (idmap_ctx = talloc_named_const(NULL, 0, "idmap_ctx")) == NULL ) {
268 return NT_STATUS_NO_MEMORY;
271 if ( (idmap_cache = idmap_cache_init(idmap_ctx)) == NULL ) {
272 return NT_STATUS_UNSUCCESSFUL;
275 return NT_STATUS_OK;
278 /****************************************************************************
279 ****************************************************************************/
281 NTSTATUS idmap_init(void)
283 NTSTATUS ret;
284 static NTSTATUS idmap_init_status = NT_STATUS_UNSUCCESSFUL;
285 struct idmap_domain *dom;
286 char *compat_backend = NULL;
287 char *compat_params = NULL;
288 const char **dom_list = NULL;
289 const char *default_domain = NULL;
290 char *alloc_backend = NULL;
291 BOOL default_already_defined = False;
292 BOOL pri_dom_is_in_list = False;
293 int compat = 0;
294 int i;
296 ret = idmap_init_cache();
297 if (!NT_STATUS_IS_OK(ret))
298 return ret;
300 if (NT_STATUS_IS_OK(idmap_init_status))
301 return NT_STATUS_OK;
303 static_init_idmap;
305 dom_list = lp_idmap_domains();
307 if ( lp_idmap_backend() ) {
308 const char **compat_list = lp_idmap_backend();
309 char *p = NULL;
310 const char *q = NULL;
312 if (dom_list) {
313 DEBUG(0, ("WARNING: idmap backend and idmap domains "
314 "are mutually excusive!\n"));
315 DEBUGADD(0,("idmap backend option will be IGNORED!\n"));
316 } else {
317 compat = 1;
319 /* strip any leading idmap_ prefix of */
320 if (strncmp(*compat_list, "idmap_", 6) == 0 ) {
321 q = *compat_list += 6;
322 DEBUG(0, ("WARNING: idmap backend uses obsolete"
323 " and deprecated 'idmap_' prefix.\n"
324 "Please replace 'idmap_%s' by '%s' in"
325 " %s\n", q, q, dyn_CONFIGFILE));
326 compat_backend = talloc_strdup(idmap_ctx, q);
327 } else {
328 compat_backend = talloc_strdup(idmap_ctx,
329 *compat_list);
332 if (compat_backend == NULL) {
333 ret = NT_STATUS_NO_MEMORY;
334 goto done;
337 /* separate the backend and module arguements */
338 if ((p = strchr(compat_backend, ':')) != NULL) {
339 *p = '\0';
340 compat_params = p + 1;
343 } else if ( !dom_list ) {
344 /* Back compatible: without idmap domains and explicit
345 idmap backend. Taking default idmap backend: tdb */
347 compat = 1;
348 compat_backend = talloc_strdup( idmap_ctx, "tdb");
349 compat_params = compat_backend;
352 if ( ! dom_list) {
353 /* generate a list with our main domain */
354 char ** dl;
356 dl = talloc_array(idmap_ctx, char *, 2);
357 if (dl == NULL) {
358 ret = NT_STATUS_NO_MEMORY;
359 goto done;
361 dl[0] = talloc_strdup(dl, lp_workgroup());
362 if (dl[0] == NULL) {
363 ret = NT_STATUS_NO_MEMORY;
364 goto done;
367 /* terminate */
368 dl[1] = NULL;
370 dom_list = dl;
371 default_domain = dl[0];
374 /***************************
375 * initialize idmap domains
377 DEBUG(1, ("Initializing idmap domains\n"));
379 for (i=0, num_domains=0; dom_list[i]; i++) {
380 const char *parm_backend;
381 char *config_option;
383 /* ignore BUILTIN and local MACHINE domains */
384 if (strequal(dom_list[i], "BUILTIN")
385 || strequal(dom_list[i], get_global_sam_name()))
387 DEBUG(0,("idmap_init: Ignoring domain %s\n",
388 dom_list[i]));
389 continue;
392 if ((dom_list[i] != default_domain) &&
393 strequal(dom_list[i], lp_workgroup())) {
394 pri_dom_is_in_list = True;
396 /* init domain */
398 dom = TALLOC_ZERO_P(idmap_ctx, struct idmap_domain);
399 IDMAP_CHECK_ALLOC(dom);
401 dom->name = talloc_strdup(dom, dom_list[i]);
402 IDMAP_CHECK_ALLOC(dom->name);
404 config_option = talloc_asprintf(dom, "idmap config %s",
405 dom->name);
406 IDMAP_CHECK_ALLOC(config_option);
408 /* default or specific ? */
410 dom->default_domain = lp_parm_bool(-1, config_option,
411 "default", False);
413 if (dom->default_domain ||
414 (default_domain && strequal(dom_list[i], default_domain))) {
416 /* make sure this is set even when we match
417 * default_domain */
418 dom->default_domain = True;
420 if (default_already_defined) {
421 DEBUG(1, ("ERROR: Multiple domains defined as"
422 " default!\n"));
423 ret = NT_STATUS_INVALID_PARAMETER;
424 goto done;
427 default_already_defined = True;
431 dom->readonly = lp_parm_bool(-1, config_option,
432 "readonly", False);
434 /* find associated backend (default: tdb) */
435 if (compat) {
436 parm_backend = talloc_strdup(idmap_ctx, compat_backend);
437 } else {
438 parm_backend = talloc_strdup(idmap_ctx,
439 lp_parm_const_string(
440 -1, config_option,
441 "backend", "tdb"));
443 IDMAP_CHECK_ALLOC(parm_backend);
445 /* get the backend methods for this domain */
446 dom->methods = get_methods(backends, parm_backend);
448 if ( ! dom->methods) {
449 ret = smb_probe_module("idmap", parm_backend);
450 if (NT_STATUS_IS_OK(ret)) {
451 dom->methods = get_methods(backends,
452 parm_backend);
455 if ( ! dom->methods) {
456 DEBUG(0, ("ERROR: Could not get methods for "
457 "backend %s\n", parm_backend));
458 ret = NT_STATUS_UNSUCCESSFUL;
459 goto done;
462 /* check the set_mapping function exists otherwise mark the
463 * module as readonly */
464 if ( ! dom->methods->set_mapping) {
465 DEBUG(5, ("Forcing to readonly, as this module can't"
466 " store arbitrary mappings.\n"));
467 dom->readonly = True;
470 /* now that we have methods,
471 * set the destructor for this domain */
472 talloc_set_destructor(dom, close_domain_destructor);
474 if (compat_params) {
475 dom->params = talloc_strdup(dom, compat_params);
476 IDMAP_CHECK_ALLOC(dom->params);
477 } else {
478 dom->params = NULL;
481 /* Finally instance a backend copy for this domain */
482 ret = dom->methods->init(dom);
483 if ( ! NT_STATUS_IS_OK(ret)) {
484 DEBUG(0, ("ERROR: Initialization failed for backend "
485 "%s (domain %s), deferred!\n",
486 parm_backend, dom->name));
488 idmap_domains = talloc_realloc(idmap_ctx, idmap_domains,
489 struct idmap_domain *, i+1);
490 if ( ! idmap_domains) {
491 DEBUG(0, ("Out of memory!\n"));
492 ret = NT_STATUS_NO_MEMORY;
493 goto done;
495 idmap_domains[num_domains] = dom;
497 /* save default domain position for future uses */
498 if (dom->default_domain) {
499 def_dom_num = num_domains;
502 /* Bump counter to next available slot */
504 num_domains++;
506 DEBUG(10, ("Domain %s - Backend %s - %sdefault - %sreadonly\n",
507 dom->name, parm_backend,
508 dom->default_domain?"":"not ",
509 dom->readonly?"":"not "));
511 talloc_free(config_option);
514 /* automatically add idmap_nss backend if needed */
515 if ((lp_server_role() == ROLE_DOMAIN_MEMBER) &&
516 ( ! pri_dom_is_in_list) &&
517 lp_winbind_trusted_domains_only()) {
519 dom = TALLOC_ZERO_P(idmap_ctx, struct idmap_domain);
520 IDMAP_CHECK_ALLOC(dom);
522 dom->name = talloc_strdup(dom, lp_workgroup());
523 IDMAP_CHECK_ALLOC(dom->name);
525 dom->default_domain = False;
526 dom->readonly = True;
528 /* get the backend methods for passdb */
529 dom->methods = get_methods(backends, "nss");
531 /* (the nss module is always statically linked) */
532 if ( ! dom->methods) {
533 DEBUG(0, ("ERROR: No methods for idmap_nss ?!\n"));
534 ret = NT_STATUS_UNSUCCESSFUL;
535 goto done;
538 /* now that we have methods,
539 * set the destructor for this domain */
540 talloc_set_destructor(dom, close_domain_destructor);
542 if (compat_params) {
543 dom->params = talloc_strdup(dom, compat_params);
544 IDMAP_CHECK_ALLOC(dom->params);
545 } else {
546 dom->params = NULL;
549 /* Finally instance a backend copy for this domain */
550 ret = dom->methods->init(dom);
551 if ( ! NT_STATUS_IS_OK(ret)) {
552 DEBUG(0, ("ERROR: Init. failed for idmap_nss ?!\n"));
553 ret = NT_STATUS_UNSUCCESSFUL;
554 goto done;
557 idmap_domains = talloc_realloc(idmap_ctx,
558 idmap_domains,
559 struct idmap_domain *,
560 num_domains+1);
561 if ( ! idmap_domains) {
562 DEBUG(0, ("Out of memory!\n"));
563 ret = NT_STATUS_NO_MEMORY;
564 goto done;
566 idmap_domains[num_domains] = dom;
568 DEBUG(10, ("Domain %s - Backend nss - not default - readonly\n",
569 dom->name ));
571 num_domains++;
574 /**** automatically add idmap_passdb backend ****/
575 dom = TALLOC_ZERO_P(idmap_ctx, struct idmap_domain);
576 IDMAP_CHECK_ALLOC(dom);
578 dom->name = talloc_strdup(dom, get_global_sam_name());
579 IDMAP_CHECK_ALLOC(dom->name);
581 dom->default_domain = False;
582 dom->readonly = True;
584 /* get the backend methods for passdb */
585 dom->methods = get_methods(backends, "passdb");
587 /* (the passdb module is always statically linked) */
588 if ( ! dom->methods) {
589 DEBUG(0, ("ERROR: No methods for idmap_passdb ?!\n"));
590 ret = NT_STATUS_UNSUCCESSFUL;
591 goto done;
594 /* now that we have methods, set the destructor for this domain */
595 talloc_set_destructor(dom, close_domain_destructor);
597 if (compat_params) {
598 dom->params = talloc_strdup(dom, compat_params);
599 IDMAP_CHECK_ALLOC(dom->params);
600 } else {
601 dom->params = NULL;
604 /* Finally instance a backend copy for this domain */
605 ret = dom->methods->init(dom);
606 if ( ! NT_STATUS_IS_OK(ret)) {
607 DEBUG(0, ("ERROR: Init. failed for idmap_passdb ?!\n"));
608 ret = NT_STATUS_UNSUCCESSFUL;
609 goto done;
612 idmap_domains = talloc_realloc(idmap_ctx,
613 idmap_domains,
614 struct idmap_domain *,
615 num_domains+1);
616 if ( ! idmap_domains) {
617 DEBUG(0, ("Out of memory!\n"));
618 ret = NT_STATUS_NO_MEMORY;
619 goto done;
621 idmap_domains[num_domains] = dom;
623 /* needed to handle special BUILTIN and wellknown SIDs cases */
624 pdb_dom_num = num_domains;
626 DEBUG(10, ("Domain %s - Backend passdb - not default - readonly\n",
627 dom->name));
629 num_domains++;
630 /**** finished adding idmap_passdb backend ****/
632 /* sort domains so that the default is the last one */
633 /* don't sort if no default domain defined */
634 if (def_dom_num != -1 && def_dom_num != num_domains-1) {
635 /* default is not last, move it */
636 struct idmap_domain *tmp;
638 if (pdb_dom_num > def_dom_num) {
639 pdb_dom_num --;
641 } else if (pdb_dom_num == def_dom_num) { /* ?? */
642 pdb_dom_num = num_domains - 1;
645 tmp = idmap_domains[def_dom_num];
647 for (i = def_dom_num; i < num_domains-1; i++) {
648 idmap_domains[i] = idmap_domains[i+1];
650 idmap_domains[i] = tmp;
651 def_dom_num = i;
655 /* Initialize alloc module */
657 DEBUG(3, ("Initializing idmap alloc module\n"));
659 alloc_backend = NULL;
660 if (compat) {
661 alloc_backend = talloc_strdup(idmap_ctx, compat_backend);
662 } else {
663 char *ab = lp_idmap_alloc_backend();
665 if (ab && (ab[0] != '\0')) {
666 alloc_backend = talloc_strdup(idmap_ctx,
667 lp_idmap_alloc_backend());
671 if ( alloc_backend ) {
673 idmap_alloc_ctx = TALLOC_ZERO_P(idmap_ctx,
674 struct idmap_alloc_context);
675 IDMAP_CHECK_ALLOC(idmap_alloc_ctx);
677 idmap_alloc_ctx->methods = get_alloc_methods(alloc_backends,
678 alloc_backend);
679 if ( ! idmap_alloc_ctx->methods) {
680 ret = smb_probe_module("idmap", alloc_backend);
681 if (NT_STATUS_IS_OK(ret)) {
682 idmap_alloc_ctx->methods =
683 get_alloc_methods(alloc_backends,
684 alloc_backend);
687 if (idmap_alloc_ctx->methods) {
689 if (compat_params) {
690 idmap_alloc_ctx->params =
691 talloc_strdup(idmap_alloc_ctx,
692 compat_params);
693 IDMAP_CHECK_ALLOC(idmap_alloc_ctx->params);
694 } else {
695 idmap_alloc_ctx->params = NULL;
698 ret = idmap_alloc_ctx->methods->init(idmap_alloc_ctx->params);
699 if ( ! NT_STATUS_IS_OK(ret)) {
700 DEBUG(0, ("ERROR: Initialization failed for "
701 "alloc backend %s, deferred!\n",
702 alloc_backend));
703 } else {
704 idmap_alloc_ctx->initialized = True;
706 } else {
707 DEBUG(2, ("idmap_init: Unable to get methods for "
708 "alloc backend %s\n",
709 alloc_backend));
710 /* certain compat backends are just readonly */
711 if ( compat ) {
712 TALLOC_FREE(idmap_alloc_ctx);
713 ret = NT_STATUS_OK;
714 } else {
715 ret = NT_STATUS_UNSUCCESSFUL;
720 /* cleanpu temporary strings */
721 TALLOC_FREE( compat_backend );
723 idmap_init_status = NT_STATUS_OK;
725 return ret;
727 done:
728 DEBUG(0, ("Aborting IDMAP Initialization ...\n"));
729 idmap_close();
731 return ret;
734 static NTSTATUS idmap_alloc_init(void)
736 NTSTATUS ret;
738 if (! NT_STATUS_IS_OK(ret = idmap_init())) {
739 return ret;
742 if ( ! idmap_alloc_ctx) {
743 return NT_STATUS_NOT_SUPPORTED;
746 if ( ! idmap_alloc_ctx->initialized) {
747 ret = idmap_alloc_ctx->methods->init(idmap_alloc_ctx->params);
748 if ( ! NT_STATUS_IS_OK(ret)) {
749 DEBUG(0, ("ERROR: Initialization failed for alloc "
750 "backend, deferred!\n"));
751 return ret;
752 } else {
753 idmap_alloc_ctx->initialized = True;
757 return NT_STATUS_OK;
760 /**************************************************************************
761 idmap allocator interface functions
762 **************************************************************************/
764 NTSTATUS idmap_allocate_uid(struct unixid *id)
766 NTSTATUS ret;
768 if (! NT_STATUS_IS_OK(ret = idmap_alloc_init())) {
769 return ret;
772 id->type = ID_TYPE_UID;
773 return idmap_alloc_ctx->methods->allocate_id(id);
776 NTSTATUS idmap_allocate_gid(struct unixid *id)
778 NTSTATUS ret;
780 if (! NT_STATUS_IS_OK(ret = idmap_alloc_init())) {
781 return ret;
784 id->type = ID_TYPE_GID;
785 return idmap_alloc_ctx->methods->allocate_id(id);
788 NTSTATUS idmap_set_uid_hwm(struct unixid *id)
790 NTSTATUS ret;
792 if (! NT_STATUS_IS_OK(ret = idmap_alloc_init())) {
793 return ret;
796 id->type = ID_TYPE_UID;
797 return idmap_alloc_ctx->methods->set_id_hwm(id);
800 NTSTATUS idmap_set_gid_hwm(struct unixid *id)
802 NTSTATUS ret;
804 if (! NT_STATUS_IS_OK(ret = idmap_alloc_init())) {
805 return ret;
808 id->type = ID_TYPE_GID;
809 return idmap_alloc_ctx->methods->set_id_hwm(id);
812 /******************************************************************************
813 Lookup an idmap_domain give a full user or group SID
814 ******************************************************************************/
816 static struct idmap_domain* find_idmap_domain_from_sid( DOM_SID *account_sid )
818 DOM_SID domain_sid;
819 uint32 rid;
820 struct winbindd_domain *domain = NULL;
821 int i;
823 /* 1. Handle BUILTIN or Special SIDs and prevent them from
824 falling into the default domain space (if we have a
825 configured passdb backend. */
827 if ( (pdb_dom_num != -1) &&
828 (sid_check_is_in_builtin(account_sid) ||
829 sid_check_is_in_wellknown_domain(account_sid) ||
830 sid_check_is_in_unix_groups(account_sid) ||
831 sid_check_is_in_unix_users(account_sid)) )
833 return idmap_domains[pdb_dom_num];
836 /* 2. Lookup the winbindd_domain from the account_sid */
838 sid_copy( &domain_sid, account_sid );
839 sid_split_rid( &domain_sid, &rid );
840 domain = find_domain_from_sid_noinit( &domain_sid );
842 for (i = 0; domain && i < num_domains; i++) {
843 if ( strequal( idmap_domains[i]->name, domain->name ) ) {
844 return idmap_domains[i];
848 /* 3. Fall back to the default domain */
850 if ( def_dom_num != -1 ) {
851 return idmap_domains[def_dom_num];
854 return NULL;
857 /******************************************************************************
858 Lookup an index given an idmap_domain pointer
859 ******************************************************************************/
861 static uint32 find_idmap_domain_index( struct idmap_domain *id_domain)
863 int i;
865 for (i = 0; i < num_domains; i++) {
866 if ( idmap_domains[i] == id_domain )
867 return i;
870 return -1;
874 /*********************************************************
875 Check if creating a mapping is permitted for the domain
876 *********************************************************/
878 static NTSTATUS idmap_can_map(const struct id_map *map,
879 struct idmap_domain **ret_dom)
881 struct idmap_domain *dom;
883 /* Check we do not create mappings for our own local domain,
884 * or BUILTIN or special SIDs */
885 if ((sid_compare_domain(map->sid, get_global_sam_sid()) == 0) ||
886 sid_check_is_in_builtin(map->sid) ||
887 sid_check_is_in_wellknown_domain(map->sid)) {
888 DEBUG(10, ("We are not supposed to create mappings for "
889 "our own domains (local, builtin, specials)\n"));
890 return NT_STATUS_UNSUCCESSFUL;
893 /* Special check for trusted domain only = Yes */
894 if (lp_winbind_trusted_domains_only()) {
895 struct winbindd_domain *wdom = find_our_domain();
896 if (wdom && (sid_compare_domain(map->sid, &wdom->sid) == 0)) {
897 DEBUG(10, ("We are not supposed to create mappings for "
898 "our primary domain when <trusted domain "
899 "only> is True\n"));
900 DEBUGADD(10, ("Leave [%s] unmapped\n",
901 sid_string_static(map->sid)));
902 return NT_STATUS_UNSUCCESSFUL;
906 if ( (dom = find_idmap_domain_from_sid( map->sid )) == NULL ) {
907 /* huh, couldn't find a suitable domain,
908 * let's just leave it unmapped */
909 DEBUG(10, ("Could not find idmap backend for SID %s\n",
910 sid_string_static(map->sid)));
911 return NT_STATUS_NO_SUCH_DOMAIN;
914 if (dom->readonly) {
915 /* ouch the domain is read only,
916 * let's just leave it unmapped */
917 DEBUG(10, ("idmap backend for SID %s is READONLY!\n",
918 sid_string_static(map->sid)));
919 return NT_STATUS_UNSUCCESSFUL;
922 *ret_dom = dom;
923 return NT_STATUS_OK;
926 static NTSTATUS idmap_new_mapping(TALLOC_CTX *ctx, struct id_map *map)
928 NTSTATUS ret;
929 struct idmap_domain *dom;
931 /* If we are offline we cannot lookup SIDs, deny mapping */
932 if (idmap_is_offline()) {
933 return NT_STATUS_FILE_IS_OFFLINE;
936 ret = idmap_can_map(map, &dom);
937 if ( ! NT_STATUS_IS_OK(ret)) {
938 return NT_STATUS_NONE_MAPPED;
941 /* check if this is a valid SID and then map it */
942 switch (map->xid.type) {
943 case ID_TYPE_UID:
944 ret = idmap_allocate_uid(&map->xid);
945 if ( ! NT_STATUS_IS_OK(ret)) {
946 /* can't allocate id, let's just leave it unmapped */
947 DEBUG(2, ("uid allocation failed! "
948 "Can't create mapping\n"));
949 return NT_STATUS_NONE_MAPPED;
951 break;
952 case ID_TYPE_GID:
953 ret = idmap_allocate_gid(&map->xid);
954 if ( ! NT_STATUS_IS_OK(ret)) {
955 /* can't allocate id, let's just leave it unmapped */
956 DEBUG(2, ("gid allocation failed! "
957 "Can't create mapping\n"));
958 return NT_STATUS_NONE_MAPPED;
960 break;
961 default:
962 /* invalid sid, let's just leave it unmapped */
963 DEBUG(3,("idmap_new_mapping: Refusing to create a "
964 "mapping for an unspecified ID type.\n"));
965 return NT_STATUS_NONE_MAPPED;
968 /* ok, got a new id, let's set a mapping */
969 map->status = ID_MAPPED;
971 DEBUG(10, ("Setting mapping: %s <-> %s %lu\n",
972 sid_string_static(map->sid),
973 (map->xid.type == ID_TYPE_UID) ? "UID" : "GID",
974 (unsigned long)map->xid.id));
975 ret = dom->methods->set_mapping(dom, map);
977 if ( ! NT_STATUS_IS_OK(ret)) {
978 /* something wrong here :-( */
979 DEBUG(2, ("Failed to commit mapping\n!"));
981 /* TODO: would it make sense to have an "unalloc_id function?" */
983 return NT_STATUS_NONE_MAPPED;
986 return NT_STATUS_OK;
989 static NTSTATUS idmap_backends_set_mapping(const struct id_map *map)
991 struct idmap_domain *dom;
992 NTSTATUS ret;
994 DEBUG(10, ("Setting mapping %s <-> %s %lu\n",
995 sid_string_static(map->sid),
996 (map->xid.type == ID_TYPE_UID) ? "UID" : "GID",
997 (unsigned long)map->xid.id));
999 ret = idmap_can_map(map, &dom);
1000 if ( ! NT_STATUS_IS_OK(ret)) {
1001 return ret;
1004 DEBUG(10,("set_mapping for domain %s\n", dom->name ));
1006 return dom->methods->set_mapping(dom, map);
1009 static NTSTATUS idmap_backends_unixids_to_sids(struct id_map **ids)
1011 struct idmap_domain *dom;
1012 struct id_map **unmapped;
1013 struct id_map **_ids;
1014 TALLOC_CTX *ctx;
1015 NTSTATUS ret;
1016 int i, u, n;
1018 if (!ids || !*ids) {
1019 DEBUG(1, ("Invalid list of maps\n"));
1020 return NT_STATUS_INVALID_PARAMETER;
1023 ctx = talloc_named_const(NULL, 0, "idmap_backends_unixids_to_sids ctx");
1024 if ( ! ctx) {
1025 DEBUG(0, ("Out of memory!\n"));
1026 return NT_STATUS_NO_MEMORY;
1029 DEBUG(10, ("Query backends to map ids->sids\n"));
1031 /* start from the default (the last one) and then if there are still
1032 * unmapped entries cycle through the others */
1034 _ids = ids;
1036 unmapped = NULL;
1037 for (n = num_domains-1; n >= 0; n--) { /* cycle backwards */
1039 dom = idmap_domains[n];
1041 DEBUG(10, ("Query sids from domain %s\n", dom->name));
1043 ret = dom->methods->unixids_to_sids(dom, _ids);
1044 IDMAP_REPORT_RET(ret);
1046 unmapped = NULL;
1048 for (i = 0, u = 0; _ids[i]; i++) {
1049 if (_ids[i]->status != ID_MAPPED) {
1050 unmapped = talloc_realloc(ctx, unmapped,
1051 struct id_map *, u + 2);
1052 IDMAP_CHECK_ALLOC(unmapped);
1053 unmapped[u] = _ids[i];
1054 u++;
1057 if (unmapped) {
1058 /* terminate the unmapped list */
1059 unmapped[u] = NULL;
1060 } else { /* no more entries, get out */
1061 break;
1064 _ids = unmapped;
1068 if (unmapped) {
1069 /* there are still unmapped ids,
1070 * map them to the unix users/groups domains */
1071 /* except for expired entries,
1072 * these will be returned as valid (offline mode) */
1073 for (i = 0; unmapped[i]; i++) {
1074 if (unmapped[i]->status == ID_EXPIRED) continue;
1075 switch (unmapped[i]->xid.type) {
1076 case ID_TYPE_UID:
1077 uid_to_unix_users_sid(
1078 (uid_t)unmapped[i]->xid.id,
1079 unmapped[i]->sid);
1080 unmapped[i]->status = ID_MAPPED;
1081 break;
1082 case ID_TYPE_GID:
1083 gid_to_unix_groups_sid(
1084 (gid_t)unmapped[i]->xid.id,
1085 unmapped[i]->sid);
1086 unmapped[i]->status = ID_MAPPED;
1087 break;
1088 default: /* what?! */
1089 unmapped[i]->status = ID_UNKNOWN;
1090 break;
1095 ret = NT_STATUS_OK;
1097 done:
1098 talloc_free(ctx);
1099 return ret;
1102 static NTSTATUS idmap_backends_sids_to_unixids(struct id_map **ids)
1104 struct id_map ***dom_ids;
1105 struct idmap_domain *dom;
1106 TALLOC_CTX *ctx;
1107 NTSTATUS ret;
1108 int i, *counters;
1110 if ( (ctx = talloc_named_const(NULL, 0, "be_sids_to_ids")) == NULL ) {
1111 DEBUG(1, ("failed to allocate talloc context, OOM?\n"));
1112 return NT_STATUS_NO_MEMORY;
1115 DEBUG(10, ("Query backends to map sids->ids\n"));
1117 /* split list per domain */
1118 if (num_domains == 0) {
1119 DEBUG(1, ("No domains available?\n"));
1120 return NT_STATUS_UNSUCCESSFUL;
1123 dom_ids = TALLOC_ZERO_ARRAY(ctx, struct id_map **, num_domains);
1124 IDMAP_CHECK_ALLOC(dom_ids);
1125 counters = TALLOC_ZERO_ARRAY(ctx, int, num_domains);
1126 IDMAP_CHECK_ALLOC(counters);
1128 /* partition the requests by domain */
1130 for (i = 0; ids[i]; i++) {
1131 uint32 idx;
1133 if ((dom = find_idmap_domain_from_sid(ids[i]->sid)) == NULL) {
1134 /* no available idmap_domain. Move on */
1135 continue;
1138 DEBUG(10,("SID %s is being handled by %s\n",
1139 sid_string_static(ids[i]->sid),
1140 dom ? dom->name : "none" ));
1142 idx = find_idmap_domain_index( dom );
1143 SMB_ASSERT( idx != -1 );
1145 dom_ids[idx] = talloc_realloc(ctx, dom_ids[idx],
1146 struct id_map *,
1147 counters[idx] + 2);
1148 IDMAP_CHECK_ALLOC(dom_ids[idx]);
1150 dom_ids[idx][counters[idx]] = ids[i];
1151 counters[idx]++;
1152 dom_ids[idx][counters[idx]] = NULL;
1155 /* All the ids have been dispatched in the right queues.
1156 Let's cycle through the filled ones */
1158 for (i = 0; i < num_domains; i++) {
1159 if (dom_ids[i]) {
1160 dom = idmap_domains[i];
1161 DEBUG(10, ("Query ids from domain %s\n", dom->name));
1162 ret = dom->methods->sids_to_unixids(dom, dom_ids[i]);
1163 IDMAP_REPORT_RET(ret);
1167 /* ok all the backends have been contacted at this point */
1168 /* let's see if we have any unmapped SID left and act accordingly */
1170 for (i = 0; ids[i]; i++) {
1171 /* NOTE: this will NOT touch ID_EXPIRED entries that the backend
1172 * was not able to confirm/deny (offline mode) */
1173 if (ids[i]->status == ID_UNKNOWN ||
1174 ids[i]->status == ID_UNMAPPED) {
1175 /* ok this is an unmapped one, see if we can map it */
1176 ret = idmap_new_mapping(ctx, ids[i]);
1177 if (NT_STATUS_IS_OK(ret)) {
1178 /* successfully mapped */
1179 ids[i]->status = ID_MAPPED;
1180 } else
1181 if (NT_STATUS_EQUAL(ret, NT_STATUS_NONE_MAPPED)) {
1182 /* could not map it */
1183 ids[i]->status = ID_UNMAPPED;
1184 } else {
1185 /* Something very bad happened down there
1186 * OR we are offline */
1187 ids[i]->status = ID_UNKNOWN;
1192 ret = NT_STATUS_OK;
1194 done:
1195 talloc_free(ctx);
1196 return ret;
1199 /**************************************************************************
1200 idmap interface functions
1201 **************************************************************************/
1203 NTSTATUS idmap_unixids_to_sids(struct id_map **ids)
1205 TALLOC_CTX *ctx;
1206 NTSTATUS ret;
1207 struct id_map **bids;
1208 int i, bi;
1209 int bn = 0;
1211 if (! NT_STATUS_IS_OK(ret = idmap_init())) {
1212 return ret;
1215 if (!ids || !*ids) {
1216 DEBUG(1, ("Invalid list of maps\n"));
1217 return NT_STATUS_INVALID_PARAMETER;
1220 ctx = talloc_named_const(NULL, 0, "idmap_unixids_to_sids ctx");
1221 if ( ! ctx) {
1222 DEBUG(1, ("failed to allocate talloc context, OOM?\n"));
1223 return NT_STATUS_NO_MEMORY;
1226 /* no ids to be asked to the backends by default */
1227 bids = NULL;
1228 bi = 0;
1230 for (i = 0; ids[i]; i++) {
1232 if ( ! ids[i]->sid) {
1233 DEBUG(1, ("invalid null SID in id_map array"));
1234 talloc_free(ctx);
1235 return NT_STATUS_INVALID_PARAMETER;
1238 ret = idmap_cache_map_id(idmap_cache, ids[i]);
1240 if ( ! NT_STATUS_IS_OK(ret)) {
1242 if ( ! bids) {
1243 /* alloc space for ids to be resolved by
1244 * backends (realloc ten by ten) */
1245 bids = TALLOC_ARRAY(ctx, struct id_map *, 10);
1246 if ( ! bids) {
1247 DEBUG(1, ("Out of memory!\n"));
1248 talloc_free(ctx);
1249 return NT_STATUS_NO_MEMORY;
1251 bn = 10;
1254 /* add this id to the ones to be retrieved
1255 * from the backends */
1256 bids[bi] = ids[i];
1257 bi++;
1259 /* check if we need to allocate new space
1260 * on the rids array */
1261 if (bi == bn) {
1262 bn += 10;
1263 bids = talloc_realloc(ctx, bids,
1264 struct id_map *, bn);
1265 if ( ! bids) {
1266 DEBUG(1, ("Out of memory!\n"));
1267 talloc_free(ctx);
1268 return NT_STATUS_NO_MEMORY;
1272 /* make sure the last element is NULL */
1273 bids[bi] = NULL;
1277 /* let's see if there is any id mapping to be retieved
1278 * from the backends */
1279 if (bi) {
1281 ret = idmap_backends_unixids_to_sids(bids);
1282 IDMAP_CHECK_RET(ret);
1284 /* update the cache */
1285 for (i = 0; i < bi; i++) {
1286 if (bids[i]->status == ID_MAPPED) {
1287 ret = idmap_cache_set(idmap_cache, bids[i]);
1288 } else if (bids[i]->status == ID_EXPIRED) {
1289 /* the cache returned an expired entry and the
1290 * backend was not able to clear the situation
1291 * (offline). This handles a previous
1292 * NT_STATUS_SYNCHRONIZATION_REQUIRED
1293 * for disconnected mode, */
1294 bids[i]->status = ID_MAPPED;
1295 } else if (bids[i]->status == ID_UNKNOWN) {
1296 /* something bad here. We were not able to
1297 * handle this for some reason, mark it as
1298 * unmapped and hope next time things will
1299 * settle down. */
1300 bids[i]->status = ID_UNMAPPED;
1301 } else { /* unmapped */
1302 ret = idmap_cache_set_negative_id(idmap_cache,
1303 bids[i]);
1305 IDMAP_CHECK_RET(ret);
1309 ret = NT_STATUS_OK;
1310 done:
1311 talloc_free(ctx);
1312 return ret;
1315 NTSTATUS idmap_sids_to_unixids(struct id_map **ids)
1317 TALLOC_CTX *ctx;
1318 NTSTATUS ret;
1319 struct id_map **bids;
1320 int i, bi;
1321 int bn = 0;
1323 if (! NT_STATUS_IS_OK(ret = idmap_init())) {
1324 return ret;
1327 if (!ids || !*ids) {
1328 DEBUG(1, ("Invalid list of maps\n"));
1329 return NT_STATUS_INVALID_PARAMETER;
1332 ctx = talloc_named_const(NULL, 0, "idmap_sids_to_unixids ctx");
1333 if ( ! ctx) {
1334 DEBUG(1, ("failed to allocate talloc context, OOM?\n"));
1335 return NT_STATUS_NO_MEMORY;
1338 /* no ids to be asked to the backends by default */
1339 bids = NULL;
1340 bi = 0;
1342 for (i = 0; ids[i]; i++) {
1344 if ( ! ids[i]->sid) {
1345 DEBUG(1, ("invalid null SID in id_map array\n"));
1346 talloc_free(ctx);
1347 return NT_STATUS_INVALID_PARAMETER;
1350 ret = idmap_cache_map_sid(idmap_cache, ids[i]);
1352 if ( ! NT_STATUS_IS_OK(ret)) {
1354 if ( ! bids) {
1355 /* alloc space for ids to be resolved
1356 by backends (realloc ten by ten) */
1357 bids = TALLOC_ARRAY(ctx, struct id_map *, 10);
1358 if ( ! bids) {
1359 DEBUG(1, ("Out of memory!\n"));
1360 talloc_free(ctx);
1361 return NT_STATUS_NO_MEMORY;
1363 bn = 10;
1366 /* add this id to the ones to be retrieved
1367 * from the backends */
1368 bids[bi] = ids[i];
1369 bi++;
1371 /* check if we need to allocate new space
1372 * on the ids array */
1373 if (bi == bn) {
1374 bn += 10;
1375 bids = talloc_realloc(ctx, bids,
1376 struct id_map *, bn);
1377 if ( ! bids) {
1378 DEBUG(1, ("Out of memory!\n"));
1379 talloc_free(ctx);
1380 return NT_STATUS_NO_MEMORY;
1384 /* make sure the last element is NULL */
1385 bids[bi] = NULL;
1389 /* let's see if there is any id mapping to be retieved
1390 * from the backends */
1391 if (bids) {
1393 ret = idmap_backends_sids_to_unixids(bids);
1394 IDMAP_CHECK_RET(ret);
1396 /* update the cache */
1397 for (i = 0; bids[i]; i++) {
1398 if (bids[i]->status == ID_MAPPED) {
1399 ret = idmap_cache_set(idmap_cache, bids[i]);
1400 } else if (bids[i]->status == ID_EXPIRED) {
1401 /* the cache returned an expired entry and the
1402 * backend was not able to clear the situation
1403 * (offline). This handles a previous
1404 * NT_STATUS_SYNCHRONIZATION_REQUIRED
1405 * for disconnected mode, */
1406 bids[i]->status = ID_MAPPED;
1407 } else if (bids[i]->status == ID_UNKNOWN) {
1408 /* something bad here. We were not able to
1409 * handle this for some reason, mark it as
1410 * unmapped and hope next time things will
1411 * settle down. */
1412 bids[i]->status = ID_UNMAPPED;
1413 } else { /* unmapped */
1414 ret = idmap_cache_set_negative_sid(idmap_cache,
1415 bids[i]);
1417 IDMAP_CHECK_RET(ret);
1421 ret = NT_STATUS_OK;
1422 done:
1423 talloc_free(ctx);
1424 return ret;
1427 NTSTATUS idmap_set_mapping(const struct id_map *id)
1429 TALLOC_CTX *ctx;
1430 NTSTATUS ret;
1432 if (! NT_STATUS_IS_OK(ret = idmap_init())) {
1433 return ret;
1436 /* sanity checks */
1437 if ((id->sid == NULL) || (id->status != ID_MAPPED)) {
1438 DEBUG(1, ("NULL SID or unmapped entry\n"));
1439 return NT_STATUS_INVALID_PARAMETER;
1442 /* TODO: check uid/gid range ? */
1444 ctx = talloc_named_const(NULL, 0, "idmap_set_mapping ctx");
1445 if ( ! ctx) {
1446 DEBUG(1, ("failed to allocate talloc context, OOM?\n"));
1447 return NT_STATUS_NO_MEMORY;
1450 /* set the new mapping */
1451 ret = idmap_backends_set_mapping(id);
1452 IDMAP_CHECK_RET(ret);
1454 /* set the mapping in the cache */
1455 ret = idmap_cache_set(idmap_cache, id);
1456 IDMAP_CHECK_RET(ret);
1458 done:
1459 talloc_free(ctx);
1460 return ret;
1463 /**************************************************************************
1464 Dump backend status.
1465 **************************************************************************/
1467 void idmap_dump_maps(char *logfile)
1469 NTSTATUS ret;
1470 struct unixid allid;
1471 struct id_map *maps;
1472 int num_maps;
1473 FILE *dump;
1474 int i;
1476 if (! NT_STATUS_IS_OK(ret = idmap_init())) {
1477 return;
1480 dump = fopen(logfile, "w");
1481 if ( ! dump) {
1482 DEBUG(0, ("Unable to open open stream for file [%s], "
1483 "errno: %d\n", logfile, errno));
1484 return;
1487 if (NT_STATUS_IS_OK(ret = idmap_alloc_init())) {
1488 allid.type = ID_TYPE_UID;
1489 allid.id = 0;
1490 idmap_alloc_ctx->methods->get_id_hwm(&allid);
1491 fprintf(dump, "USER HWM %lu\n", (unsigned long)allid.id);
1493 allid.type = ID_TYPE_GID;
1494 allid.id = 0;
1495 idmap_alloc_ctx->methods->get_id_hwm(&allid);
1496 fprintf(dump, "GROUP HWM %lu\n", (unsigned long)allid.id);
1499 maps = talloc(idmap_ctx, struct id_map);
1500 num_maps = 0;
1502 for (i = 0; i < num_domains; i++) {
1503 if (idmap_domains[i]->methods->dump_data) {
1504 idmap_domains[i]->methods->dump_data(idmap_domains[i],
1505 &maps, &num_maps);
1509 for (i = 0; i < num_maps; i++) {
1510 switch (maps[i].xid.type) {
1511 case ID_TYPE_UID:
1512 fprintf(dump, "UID %lu %s\n",
1513 (unsigned long)maps[i].xid.id,
1514 sid_string_static(maps[i].sid));
1515 break;
1516 case ID_TYPE_GID:
1517 fprintf(dump, "GID %lu %s\n",
1518 (unsigned long)maps[i].xid.id,
1519 sid_string_static(maps[i].sid));
1520 break;
1521 case ID_TYPE_NOT_SPECIFIED:
1522 break;
1526 fflush(dump);
1527 fclose(dump);
1530 char *idmap_fetch_secret(const char *backend, bool alloc,
1531 const char *domain, const char *identity)
1533 char *tmp, *ret;
1534 int r;
1536 if (alloc) {
1537 r = asprintf(&tmp, "IDMAP_ALLOC_%s", backend);
1538 } else {
1539 r = asprintf(&tmp, "IDMAP_%s_%s", backend, domain);
1542 if (r < 0)
1543 return NULL;
1545 strupper_m(tmp); /* make sure the key is case insensitive */
1546 ret = secrets_fetch_generic(tmp, identity);
1548 SAFE_FREE(tmp);
1550 return ret;