Changes between Version 17 and Version 18 of TracUserSyncPlugin
- Timestamp:
- Aug 27, 2015, 11:55:27 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracUserSyncPlugin
v17 v18 1 = Synchronize User Account data between multiple Trac projects = 2 [[TOC]] 1 [[PageOutline(2-5,Contents,pullout)]] 2 3 = Synchronize User Account data between multiple Trac projects 3 4 4 5 {{{ … … 9 10 }}} 10 11 11 == Description == 12 This plugin can be used to synchronize user account data between multiple projects within the same `TRAC_PARENT`. Basically, it reads the account information from all the separate environments, merges them, and then updates all environments accordingly. As it currently still is in early beta state at best, a `dryrun` mode is enabled by default - so no changes will be written to the database. Instead, the updates for the affected environments will be stored in `<tracenv>.sql` files to investigate. 12 == Description 13 13 14 If you intend to use this plugin in its current state, you are strongly encouraged to... 14 This plugin can be used to synchronize user account data between multiple projects within the same `TRAC_PARENT`. It reads the account information from all the separate environments, merges them, and then updates all environments accordingly. As it currently still is in early beta state at best, a `dryrun` mode is enabled by default - so no changes will be written to the database. Instead, the updates for the affected environments will be stored in `<tracenv>.sql` files to investigate. 15 16 If you intend to use this plugin in its current state, you are strongly encouraged to: 15 17 1. first test it in a non-productive environment, best is a copy of the intended productive environment to be used on later 16 18 1. first let it run in `drymode`, and investigate the resulting `*.sql` files carefully (see [#Usage below]) … … 18 20 1. only if still everything seems to be OK, repeat these steps in your productive environment - at your own risk 19 21 20 I (the author) will take no responsibilities whatever, especially concerning possible damage and data loss. You have been warned!21 22 22 If you are still eager to try it: Great - I love to receive your feedback! 23 23 24 == Limitations == 24 === Limitations 25 25 26 Except this plugin being still in early beta state, there are more limitations to consider: 26 27 1. it was not widely tested yet 27 28 1. it is not yet "fool-proof" (if it ever will be). This especially means, not all possible exceptions may be handled yet 28 1. it works only for environments, which ...29 1. it works only for environments, which meet the following conditions: 29 30 1. share the same `TRAC_PARENT_DIR` 30 31 1. use the AccountManagerPlugin 31 32 1. store the user passwords in a `.htpasswd` file 32 33 1. share the same `.htpasswd` password file 33 There may be more limitations I'm not aware of at the moment...34 34 35 == Bugs/Feature Requests ==35 == Bugs/Feature Requests 36 36 37 37 Existing bugs and feature requests for TracUserSyncPlugin are … … 39 39 40 40 If you have any issues, create a 41 [ http://trac-hacks.org/newticket?component=TracUserSyncPlugin&owner=izzynew ticket].41 [/newticket?component=TracUserSyncPlugin new ticket]. 42 42 43 == Download == 43 [[TicketQuery(component=TracUserSyncPlugin&group=type,format=progress)]] 44 45 == Download 44 46 45 47 Download the zipped source from [download:tracusersyncplugin here]. 46 48 47 == Source ==49 == Source 48 50 49 51 You can check out TracUserSyncPlugin from [http://trac-hacks.org/svn/tracusersyncplugin here] using Subversion, or [source:tracusersyncplugin browse the source] with Trac. 50 52 51 == Versions == 53 === Versions 54 52 55 * [http://trac-hacks.org/svn/tracusersyncplugin/0.11/branches/0.1 0.1]: Basic synchronization 53 56 * [http://trac-hacks.org/svn/tracusersyncplugin/0.11/trunk current trunk]: adds purge functionality 54 57 55 == Installation == 58 == Installation 59 56 60 The easiest way to install this plugin is: 57 {{{ 61 {{{#!sh 58 62 easy_install http://trac-hacks.org/svn/tracusersyncplugin/0.11/trunk 59 63 }}} 64 60 65 While you may want to replace "trunk" by one of the branches. "trunk" is usually the "code in development", while the branches should reflect something "stable". 61 66 62 67 You can also checkout the code from the repository, or download and unpack the zipped source (see above) - and then run either `easy_install` or `python setup.py` from where the `setup.py` file resides. 63 68 64 == Configuration == 69 == Configuration 70 65 71 First you of course need to activate the plugin. This is, as usual, done in the components section of your `trac.ini`: 66 {{{ 72 {{{#!ini 67 73 [components] 68 74 tracusersync.* = enabled 69 75 }}} 70 76 71 For testing purposes, default settings should be fine. However, there are some settings you can use for "fine-tuning" - they are to be found (or inserted) in(to) your `trac.ini` in the `[user_sync]` section as shown below:72 {{{ 77 For testing purposes, default settings should be fine. However, there are some settings you can use for "fine-tuning" - they are to be found (or inserted) in(to) your `trac.ini` in the `[user_sync]` section: 78 {{{#!ini 73 79 [user_sync] 74 80 dryrun = true … … 79 85 exclude_envs = 80 86 }}} 87 81 88 The easiest way to modify these settings is using the IniAdminPlugin, where you always have some helpful information displayed next to the options. I will explain them here in short, though: 82 89 83 === dryrun === 90 === dryrun 91 84 92 This enables the "test mode", in which no changes won't be done to your environments - especially the databases will not be written to. Instead, changes which would be written to the database will be stored in `*.sql` files, one for each environment. This is a boolean setting - so the only valid values here are "true" and "false". 85 93 86 === merge_conflicts === 94 === merge_conflicts 95 87 96 What should be done if records from two (or more) environments conflict. Possible values are "skip" (do not update this user anywhere) and "newer" (use the record from the environment the user was last active in - which must not necessarily be the one with the most recent data). Default is "skip", to be on the safe side. 88 97 89 98 What makes a conflict? Say user Tom registers in environment A, and sets his name to "Tom Sawyer" and his email to "tom@sawyer.tld". His password is stored to the shared `.htpasswd` file, so he can immediately login to environment B without registering again. He does so - but edits his record here, using the name "Tommy". If the field `name` is contained in the `sync_fields` list (see below), this would cause a conflict since the two names don't match - which means, the email won't be synchronized either. The same applies the other way round: If a different email was specified in one environment, the entire record would be considered conflicting. 90 99 91 === sql_file_path === 100 === sql_file_path 101 92 102 The path where the `*.sql` files shall be stored into. If not set, they will be written into the `log` sub directory of the environment the plugin was invoked from. 93 103 94 === sync_fields === 104 === sync_fields 105 95 106 Which fields of the user records should be considered for synchronization. By default, this is set to `name,email` - the two basic fields. If you use the UserManagerPlugin, you may want to add some more fields. Note that for now a single conflict on any of the fields will exclude a user record from being merged (though this may change in the future) - so the more fields added, the higher are chances for conflicts. 96 107 97 108 There are two more fields considered here, even if not mentioned (and you should never introduce them into that list): the information used by the email verification. This means, if you enabled email verification in the AccountManagerPlugin, we will try to take care for that as well. So if a user verified for one environment, we try to do this for the other environments as well. 98 109 99 === users_keep === 110 === users_keep 111 100 112 This option only affects purging: here you can define users which shall always be excluded from purging. The plugin will take care for your permission groups (e.g. anonymous,authenticated) automatically, so you don't need to add those (if your check - see [#Results below] - shows the plugin missed one, you might add it here, though). 101 113 102 === exclude_envs === 114 === exclude_envs 115 103 116 A comma separated list of environments to exclude from our actions by default. The only effect here is that the corresponding check boxes in the web_ui will ''not'' be checked then. 104 117 105 == Usage == 106 === Settings === 118 == Usage 119 120 === Settings 121 107 122 You will find the interface on the Admin page in the Accounts section as ''User Sync'' (see also [#Example below screenshot]). After invoking this page, you can select the environments to synchronize. The list includes all Trac environments sharing the `TRAC_PARENT_DIR` with the environment you are currently in - though it did not yet check what password store they are using or even whether they share the same password file (this may be added later). If your selection includes an environment with conflicting data, it will be excluded later. All found environments are pre-selected except those mentioned in the `exclude_envs` setting - so you might want to (un)check one/some or leave it as is. 108 123 … … 111 126 The third section lets you select the actions to perform. ''Synchronize'' is already pre-selected here, since this is the main task this plugin is for, and also is what you probably want to do. This action means: Make sure all included environments get the account data users have entered in one of the environments for fields contained in the `sync_fields` setting. The second check box, labeled ''Purge'', will cause the plugin to remove all users from all environments - except those contained in the password file or mentioned in the `users_keep` setting. Of course, it would not touch your permission groups (anonymous,authenticated, and whatever you may have added) - these are evaluated automatically. 112 127 113 {{{ 114 #!html 128 {{{#!html 115 129 <DIV STYLE='background: #fdc; border: 2px solid #d00; color: #500; padding: .5em; margin: 1em 0;'> 116 130 <B STYLE='color:#f00;'>WARNING:</B> You should always run in <code>dryrun</code> mode first and check the resulting <code>*.sql</code> files carefully. Every Trac setup has its specifics, and I only tested the script in my own setup. So as long as there's no feedback from other users, I'd consider it not-yet-safe! … … 118 132 }}} 119 133 120 === Results === 134 === Results 135 121 136 Now that you've made your selections, push the ''Perform actions'' button. When the page is reloaded, it will inform you about the results: 122 137 … … 130 145 * Check the `UPDATE` statements in the same way, if there are any - in this case, the corresponding `SELECT` '''must''' return a record, but not necessarily with the same data (hence the update) 131 146 132 === Hot run === 133 You may disable the `dryrun` mode once you finished the checks above. Well, you may even disable it immediately - but that's currently not recommended :-) Once you are sure everything works fine, you can even disable the writing of the `*.sql` files by setting the `sql_file_path = none` in your `trac.ini`. 147 === Hot run 134 148 135 == Example == 149 You may disable the `dryrun` mode once you finished the checks above. Well, you may even disable it immediately - but that's currently not recommended. Once you are sure everything works fine, you can even disable the writing of the `*.sql` files by setting the `sql_file_path = none` in your `trac.ini`. 150 151 == Example 152 136 153 This is what it could look like after a successful synchronization: 137 154 138 155 [[Image(tus.jpg)]] 139 156 140 == Future == 157 == Future 158 141 159 There are some things I consider for the future: 142 160 1. only list "compatible" environments (i.e. those sharing the same password file, and where the current user has the required privileges) … … 145 163 1. introduce some "Listeners" (to notice registrations/changes in environments and automatically propagate them to the other environments, so you only need to run the synchronization manually once - which is after installation). 146 164 147 I have to say here: This is not a promise. I wrote all this in my free time, and I will only continue it if my time permits me to. And believe me, I have some more projects and things I like to do, so don't get mad at me if I delay (or even stop). But hey, in those cases you've got the source, right? 165 == User Comments 148 166 149 == User Comments == 150 * Your feedback here, please :-) 167 * Your feedback here, please. 151 168 152 169 [[Poll(Let others know what you think about the TracUserSyncPlugin:;I use it and I like it!;I use it and find it acceptable.;I tried it and didn't like it;I think it's great stuff and will give it a try!;It might be good - but I'd rather wait until it's declared stable.;I don't know what to think about it.)]] 153 170 154 == Recent Changes ==171 == Recent Changes 155 172 156 [[ChangeLog(tracusersyncplugin, 4)]]173 [[ChangeLog(tracusersyncplugin, 3)]] 157 174 158 == Author/Contributors ==175 == Author/Contributors 159 176 160 177 '''Author:''' [wiki:izzy] [[BR]] 178 '''Maintainer:''' [[Maintainer]] [[BR]] 161 179 '''Contributors:'''
