windows-package-manager.rst 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908
  1. .. _windows-package-manager:
  2. ===========================
  3. Windows Software Repository
  4. ===========================
  5. .. note::
  6. In 2015.8.0 and later, the Windows Software Repository cache is compiled on
  7. the Salt Minion, which enables pillar, grains and other things to be
  8. available during compilation time. To support this new functionality,
  9. a next-generation (ng) package repository was created. See the
  10. :ref:`Changes in Version 2015.8.0 <2015-8-0-winrepo-changes>` for details.
  11. The SaltStack Windows Software Repository provides a package manager and software
  12. repository similar to what is provided by yum and apt on Linux. This repository
  13. enables the installation of software using the installers on remote Windows
  14. systems.
  15. In many senses, the operation is similar to that of
  16. the other package managers salt is aware of:
  17. - the ``pkg.installed`` and similar states work on Windows.
  18. - the ``pkg.install`` and similar module functions work on Windows.
  19. High level differences to yum and apt are:
  20. - The repository metadata (SLS files) is hosted through either salt or
  21. git.
  22. - Packages can be downloaded from within the salt repository, a git
  23. repository or from HTTP(S) or FTP URLs.
  24. - No dependencies are managed. Dependencies between packages needs to
  25. be managed manually.
  26. Requirements:
  27. - GitPython 0.3 or later, or pygit2 0.20.3 with libgit 0.20.0 or later installed
  28. on your Salt master. The Windows package definitions are downloaded
  29. and updated using Git.
  30. Configuration
  31. =============
  32. Populate the Repository
  33. -----------------------
  34. The SLS files used to install Windows packages are not distributed by default with
  35. Salt. Run the following command to initialize the repository on your Salt
  36. master:
  37. .. code-block:: bash
  38. salt-run winrepo.update_git_repos
  39. Sync Repo to Windows Minions
  40. ----------------------------
  41. Run ``pkg.refresh_db`` on each of your Windows minions to synchronize
  42. the package repository.
  43. .. code-block:: bash
  44. salt -G 'os:windows' pkg.refresh_db
  45. .. note::
  46. Use ``pkg.refresh_db`` from 2016.11 when developing new Windows package
  47. definitions to check for errors in the definitions against one or more
  48. Windows minions.
  49. Install Windows Software
  50. ========================
  51. After completing the configuration steps, you are ready to manage software on your
  52. Windows minions.
  53. Show Installed Packages
  54. -----------------------
  55. .. code-block:: bash
  56. salt -G 'os:windows' pkg.list_pkgs
  57. Install a Package
  58. -----------------
  59. You can query the available version of a package using the Salt pkg module.
  60. .. code-block:: bash
  61. salt winminion pkg.list_available firefox
  62. winminion:
  63. - 15.0.1
  64. - 16.0.2
  65. - 17.0.1
  66. As you can see, there are three versions of Firefox available for installation.
  67. You can refer a software package by its ``name`` or its ``full_name`` surround
  68. by single quotes.
  69. .. code-block:: bash
  70. salt winminion pkg.install 'firefox'
  71. The above line will install the latest version of Firefox.
  72. .. code-block:: bash
  73. salt winminion pkg.install 'firefox' version=16.0.2
  74. The above line will install version 16.0.2 of Firefox.
  75. If a different version of the package is already installed it will be replaced
  76. with the version in the winrepo (only if the package itself supports live
  77. updating).
  78. You can also specify the full name:
  79. .. code-block:: bash
  80. salt winminion pkg.install 'Mozilla Firefox 17.0.1 (x86 en-US)'
  81. Uninstall Windows Software
  82. ==========================
  83. Uninstall software using the pkg module:
  84. .. code-block:: bash
  85. salt winminion pkg.remove firefox
  86. salt winminion pkg.purge firefox
  87. .. note::
  88. ``pkg.purge`` just executes ``pkg.remove`` on Windows. At some point in the
  89. future ``pkg.purge`` may direct the installer to remove all configs and
  90. settings for software packages that support that option.
  91. Repository Location
  92. ===================
  93. Salt maintains a repository of SLS files to install a large number of Windows
  94. packages:
  95. - 2015.8.0 and later minions: https://github.com/saltstack/salt-winrepo-ng
  96. - Earlier releases: https://github.com/saltstack/salt-winrepo
  97. By default, these repositories are mirrored to ``/srv/salt/win/repo-ng``
  98. and ``/srv/salt/win/repo``.
  99. This location can be changed in the master config file by setting the
  100. :conf_master:`winrepo_dir_ng` and :conf_master:`winrepo_dir` options.
  101. Maintaining Windows Repo Definitions in Git Repositories
  102. ========================================================
  103. Windows software package definitions can be hosted in one or more Git
  104. repositories. The default repositories are hosted on GitHub by SaltStack. These
  105. include software definition files for various open source software projects.
  106. These software definition files are ``.sls`` files. There are two default
  107. repositories: ``salt-winrepo`` and ``salt-winrepo-ng``. ``salt-winrepo``
  108. contains software definition files for older minions (older than 2015.8.0).
  109. ``salt-winrepo-ng`` is for newer minions (2015.8.0 and newer).
  110. Each software definition file contains all the information salt needs to install
  111. that software on a minion including the HTTP or FTP locations of the installer
  112. files, required command-line switches for silent install, etc. Anyone is welcome
  113. to send a pull request to this repo to add new package definitions. The repos
  114. can be browsed here:
  115. `salt-winrepo`_
  116. `salt-winrepo-ng`_
  117. .. _salt-winrepo: https://github.com/saltstack/salt-winrepo.git
  118. .. _salt-winrepo-ng: https://github.com/saltstack/salt-winrepo-ng.git
  119. .. note::
  120. The newer software definition files are run through the salt's parser which
  121. allows for the use of jinja.
  122. Configure which git repositories the master can search for package definitions
  123. by modifying or extending the :conf_master:`winrepo_remotes` and
  124. :conf_master:`winrepo_remotes_ng` options.
  125. .. important::
  126. ``winrepo_remotes`` was called ``win_gitrepos`` in Salt versions earlier
  127. than 2015.8.0
  128. Package definitions are pulled down from the online git repository by running the
  129. :mod:`winrepo.update_git_repos <salt.runners.winrepo.update_git_repos>` runner.
  130. This command is run on the master:
  131. .. code-block:: bash
  132. salt-run winrepo.update_git_repos
  133. This will pull down the software definition files for older minions
  134. (``salt-winrepo``) and new minions (``salt-winrepo-ng``). They are stored in the
  135. ``file_roots`` under ``win/repo/salt-winrepo`` and
  136. ``win/repo-ng/salt-winrepo-ng`` respectively.
  137. .. important::
  138. If you have customized software definition files that aren't maintained in a
  139. repository, those should be stored under ``win/repo`` for older minions and
  140. ``win/repo-ng`` for newer minions. The reason for this is that the contents
  141. of ``win/repo/salt-winrepo`` and ``win/repo-ng/salt-winrepo-ng`` are wiped
  142. out every time you run a ``winrepo.update_git_repos``.
  143. Additionally, when you run ``winrepo.genrepo`` and ``pkg.refresh_db`` the
  144. entire contents under ``win/repo`` and ``win/repo-ng``, to include all
  145. subdirectories, are used to create the meta database file.
  146. The next step (if you have older minions) is to create the meta database file for the
  147. repo (``winrepo.p``). This is done by running the
  148. :mod:`winrepo.genrepo <salt.runners.winrepo.genrepo>` runner. This is also run
  149. on the master:
  150. .. code-block:: bash
  151. salt-run winrepo.genrepo
  152. .. note::
  153. If you have only 2015.8.0 and newer minions, you no longer need to run
  154. ``salt-run winrepo.genrepo`` on the master.
  155. Finally, you need to refresh the minion database by running the
  156. :py:func:`pkg.refresh_db <salt.modules.win_pkg.refresh_db>` command. This is run
  157. on the master as well:
  158. .. code-block:: bash
  159. salt '*' pkg.refresh_db
  160. On older minions (older than 2015.8.0) this will copy the winrepo.p file down to
  161. the minion. On newer minions (2015.8.0 and newer) this will copy all the
  162. software definition files (.sls) down to the minion and then create the meta
  163. database file (``winrepo.p``) locally. The reason this is done locally is because the
  164. jinja needs to be parsed using the minion's grains.
  165. .. important::
  166. Every time you modify the software definition files on the master, either by
  167. running ``salt-run winrepo.update_git_repos``, modifying existing files, or
  168. by creating your own, you need to refresh the database on your minions. For
  169. older minions, that means running ``salt-run winrepo.genrepo`` and then
  170. ``salt '*' pkg.refresh_db``. For newer minions (2015.8.0 and newer) it is
  171. just ``salt '*' pkg.refresh_db``.
  172. .. note::
  173. If the ``winrepo.genrepo`` or the ``pkg.refresh_db`` fails, it is likely a
  174. problem with the jinja in one of the software definition files. This will
  175. cause the operations to stop. You'll need to fix the syntax in order for the
  176. meta database file to be created successfully.
  177. To disable one of the repos, set it to an empty list ``[]`` in the master
  178. config. For example, to disable :conf_master:`winrepo_remotes` set the following
  179. in the master config file:
  180. .. code-block:: bash
  181. winrepo_remotes: []
  182. Creating a Package Definition SLS File
  183. ======================================
  184. The package definition file is a YAML file that contains all the information
  185. needed to install a piece of software using salt. It defines information about
  186. the package to include version, full name, flags required for the installer and
  187. uninstaller, whether or not to use the Windows task scheduler to install the
  188. package, where to find the installation package, etc.
  189. Take a look at this example for Firefox:
  190. .. code-block:: yaml
  191. firefox:
  192. '17.0.1':
  193. installer: 'salt://win/repo/firefox/English/Firefox Setup 17.0.1.exe'
  194. full_name: Mozilla Firefox 17.0.1 (x86 en-US)
  195. locale: en_US
  196. reboot: False
  197. install_flags: '-ms'
  198. uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
  199. uninstall_flags: '/S'
  200. '16.0.2':
  201. installer: 'salt://win/repo/firefox/English/Firefox Setup 16.0.2.exe'
  202. full_name: Mozilla Firefox 16.0.2 (x86 en-US)
  203. locale: en_US
  204. reboot: False
  205. install_flags: '-ms'
  206. uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
  207. uninstall_flags: '/S'
  208. '15.0.1':
  209. installer: 'salt://win/repo/firefox/English/Firefox Setup 15.0.1.exe'
  210. full_name: Mozilla Firefox 15.0.1 (x86 en-US)
  211. locale: en_US
  212. reboot: False
  213. install_flags: '-ms'
  214. uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
  215. uninstall_flags: '/S'
  216. Each software definition file begins with a package name for the software. As in
  217. the example above ``firefox``. The next line is indented two spaces and contains
  218. the version to be defined. As in the example above, a software definition file
  219. can define multiple versions for the same piece of software. The lines following
  220. the version are indented two more spaces and contain all the information needed
  221. to install that package.
  222. .. warning::
  223. The package name and the ``full_name`` must be unique to all other packages
  224. in the software repository.
  225. The version line is the version for the package to be installed. It is used when
  226. you need to install a specific version of a piece of software.
  227. .. warning::
  228. The version must be enclosed in quotes, otherwise the YAML parser will
  229. remove trailing zeros.
  230. .. note::
  231. There are unique situations where previous versions are unavailable. Take
  232. Google Chrome for example. There is only one URL provided for a standalone
  233. installation of Google Chrome.
  234. (https://dl.google.com/edgedl/chrome/install/GoogleChromeStandaloneEnterprise.msi)
  235. When a new version is released, the URL just points to the new version. To
  236. handle situations such as these, set the version to `latest`. Salt will
  237. install the version of Chrome at the URL and report that version. Here's an
  238. example:
  239. .. code-block:: yaml
  240. chrome:
  241. latest:
  242. full_name: 'Google Chrome'
  243. installer: 'https://dl.google.com/edgedl/chrome/install/GoogleChromeStandaloneEnterprise.msi'
  244. install_flags: '/qn /norestart'
  245. uninstaller: 'https://dl.google.com/edgedl/chrome/install/GoogleChromeStandaloneEnterprise.msi'
  246. uninstall_flags: '/qn /norestart'
  247. msiexec: True
  248. locale: en_US
  249. reboot: False
  250. Available parameters are as follows:
  251. :param str full_name:
  252. The Full Name for the software as shown in "Programs and Features" in the
  253. control panel. You can also get this information by installing the package
  254. manually and then running ``pkg.list_pkgs``. Here's an example of the output
  255. from ``pkg.list_pkgs``:
  256. .. code-block:: bash
  257. salt 'test-2008' pkg.list_pkgs
  258. test-2008
  259. ----------
  260. 7-Zip 9.20 (x64 edition):
  261. 9.20.00.0
  262. Microsoft .NET Framework 4 Client Profile:
  263. 4.0.30319,4.0.30319
  264. Microsoft .NET Framework 4 Extended:
  265. 4.0.30319,4.0.30319
  266. Microsoft Visual C++ 2008 Redistributable - x64 9.0.21022:
  267. 9.0.21022
  268. Mozilla Firefox 17.0.1 (x86 en-US):
  269. 17.0.1
  270. Mozilla Maintenance Service:
  271. 17.0.1
  272. NSClient++ (x64):
  273. 0.3.8.76
  274. Notepad++:
  275. 6.4.2
  276. Salt Minion 0.16.0:
  277. 0.16.0
  278. Notice the Full Name for Firefox: ``Mozilla Firefox 17.0.0 (x86 en-US)``.
  279. That's exactly what's in the ``full_name`` parameter in the software
  280. definition file.
  281. If any of the software installed on the machine matches one of the software
  282. definition files in the repository, the full_name will be automatically
  283. renamed to the package name. The example below shows the ``pkg.list_pkgs``
  284. for a machine that already has Mozilla Firefox 17.0.1 installed.
  285. .. code-block:: bash
  286. test-2008:
  287. ----------
  288. 7zip:
  289. 9.20.00.0
  290. Microsoft .NET Framework 4 Client Profile:
  291. 4.0.30319,4.0.30319
  292. Microsoft .NET Framework 4 Extended:
  293. 4.0.30319,4.0.30319
  294. Microsoft Visual C++ 2008 Redistributable - x64 9.0.21022:
  295. 9.0.21022
  296. Mozilla Maintenance Service:
  297. 17.0.1
  298. Notepad++:
  299. 6.4.2
  300. Salt Minion 0.16.0:
  301. 0.16.0
  302. firefox:
  303. 17.0.1
  304. nsclient:
  305. 0.3.9.328
  306. .. important::
  307. The version number and ``full_name`` need to match the output from
  308. ``pkg.list_pkgs`` so that the status can be verified when running a
  309. highstate.
  310. .. note::
  311. It is still possible to successfully install packages using
  312. ``pkg.install``, even if the ``full_name`` or the version number don't
  313. match. However, this can make troubleshooting issues difficult, so be
  314. careful.
  315. .. tip::
  316. To force salt to display the full name when there's already an existing
  317. package definition file on the system, you can pass a bogus ``saltenv``
  318. parameter to the command like so: ``pkg.list_pkgs saltenv=NotARealEnv``
  319. :param str installer:
  320. The path to the ``.exe`` or ``.msi`` to use to install the package. This can
  321. be a path or a URL. If it is a URL or a salt path (``salt://``), the package
  322. will be cached locally and then executed. If it is a path to a file on disk
  323. or a file share, it will be executed directly.
  324. .. note::
  325. If storing software in the same location as the winrepo it is best
  326. practice to place each installer in its own directory rather than the
  327. root of winrepo. Then you can place your package definition file in the
  328. same directory. It is best practice to name the file ``init.sls``. This
  329. will be picked up by ``pkg.refresh_db`` and processed properly.
  330. :param str install_flags:
  331. Any flags that need to be passed to the installer to make it perform a
  332. silent install. These can often be found by adding ``/?`` or ``/h`` when
  333. running the installer from the command-line. A great resource for finding
  334. these silent install flags can be found on the WPKG project's wiki_:
  335. .. warning::
  336. Salt will not return if the installer is waiting for user input so it is
  337. imperative that the software package being installed has the ability to
  338. install silently.
  339. :param str uninstaller:
  340. The path to the program used to uninstall this software. This can be the
  341. path to the same `exe` or `msi` used to install the software. It can also be
  342. a GUID. You can find this value in the registry under the following keys:
  343. - Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall
  344. - Software\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall
  345. :param str uninstall_flags:
  346. Any flags that need to be passed to the uninstaller to make it perform a
  347. silent uninstall. These can often be found by adding ``/?`` or ``/h`` when
  348. running the uninstaller from the command-line. A great resource for finding
  349. these silent install flags can be found on the WPKG project's wiki_:
  350. .. warning::
  351. Salt will not return if the uninstaller is waiting for user input so it
  352. is imperative that the software package being uninstalled has the
  353. ability to uninstall silently.
  354. Here are some examples of installer and uninstaller settings:
  355. .. code-block:: yaml
  356. 7zip:
  357. '9.20.00.0':
  358. installer: salt://win/repo/7zip/7z920-x64.msi
  359. full_name: 7-Zip 9.20 (x64 edition)
  360. reboot: False
  361. install_flags: '/qn /norestart'
  362. msiexec: True
  363. uninstaller: '{23170F69-40C1-2702-0920-000001000000}'
  364. uninstall_flags: '/qn /norestart'
  365. Alternatively the ``uninstaller`` can also simply repeat the URL of an msi
  366. file:
  367. .. code-block:: yaml
  368. 7zip:
  369. '9.20.00.0':
  370. installer: salt://win/repo/7zip/7z920-x64.msi
  371. full_name: 7-Zip 9.20 (x64 edition)
  372. reboot: False
  373. install_flags: '/qn /norestart'
  374. msiexec: True
  375. uninstaller: salt://win/repo/7zip/7z920-x64.msi
  376. uninstall_flags: '/qn /norestart'
  377. :param msiexec:
  378. This tells salt to use ``msiexec /i`` to install the package and
  379. ``msiexec /x`` to uninstall. This is for ``.msi`` installations. Possible
  380. options are: True, False or the path to ``msiexec.exe`` on your system
  381. .. code-block:: yaml
  382. 7zip:
  383. '9.20.00.0':
  384. installer: salt://win/repo/7zip/7z920-x64.msi
  385. full_name: 7-Zip 9.20 (x64 edition)
  386. reboot: False
  387. install_flags: '/qn /norestart'
  388. msiexec: 'C:\Windows\System32\msiexec.exe'
  389. uninstaller: salt://win/repo/7zip/7z920-x64.msi
  390. uninstall_flags: '/qn /norestart'
  391. :param bool allusers:
  392. This parameter is specific to ``.msi`` installations. It tells ``msiexec``
  393. to install the software for all users. The default is ``True``.
  394. :param bool cache_dir:
  395. If ``True`` and the installer URL begins with ``salt://``, the entire
  396. directory where the installer resides will be recursively cached. This is
  397. useful for installers that depend on other files in the same directory for
  398. installation.
  399. .. warning::
  400. Be aware that all files and directories in the same location as the
  401. installer file will be copied down to the minion. If you place your
  402. installer file in the root of winrepo (``/srv/salt/win/repo-ng``) and
  403. ``cache_dir: True`` the entire contents of winrepo will be cached to
  404. the minion. Therefore, it is best practice to place your installer files
  405. in a subdirectory if they are to be stored in winrepo.
  406. :param str cache_file:
  407. When the installer URL begins with ``salt://``, this indicates a single file
  408. to copy down for use with the installer. It is copied to the same location
  409. as the installer. Use this over ``cache_dir`` if there are many files in the
  410. directory and you only need a specific file and don't want to cache
  411. additional files that may reside in the installer directory.
  412. Here's an example for a software package that has dependent files:
  413. .. code-block:: yaml
  414. sqlexpress:
  415. '12.0.2000.8':
  416. installer: 'salt://win/repo/sqlexpress/setup.exe'
  417. full_name: Microsoft SQL Server 2014 Setup (English)
  418. reboot: False
  419. install_flags: '/ACTION=install /IACCEPTSQLSERVERLICENSETERMS /Q'
  420. cache_dir: True
  421. :param bool use_scheduler:
  422. If ``True``, Windows will use the task scheduler to run the installation.
  423. This is useful for running the Salt installation itself as the installation
  424. process kills any currently running instances of Salt.
  425. :param str source_hash:
  426. This tells Salt to compare a hash sum of the installer to the provided hash
  427. sum before execution. The value can be formatted as
  428. ``<hash_algorithm>=<hash_sum>``, or it can be a URI to a file containing the
  429. hash sum.
  430. For a list of supported algorithms, see the `hashlib documentation
  431. <https://docs.python.org/2/library/hashlib.html>`_.
  432. Here's an example of source_hash usage:
  433. .. code-block:: yaml
  434. messageanalyzer:
  435. '4.0.7551.0':
  436. full_name: 'Microsoft Message Analyzer'
  437. installer: 'salt://win/repo/messageanalyzer/MessageAnalyzer64.msi'
  438. install_flags: '/quiet /norestart'
  439. uninstaller: '{1CC02C23-8FCD-487E-860C-311EC0A0C933}'
  440. uninstall_flags: '/quiet /norestart'
  441. msiexec: True
  442. source_hash: 'sha1=62875ff451f13b10a8ff988f2943e76a4735d3d4'
  443. :param bool reboot: Not implemented
  444. :param str locale: Not implemented
  445. Examples can be found at https://github.com/saltstack/salt-winrepo-ng
  446. .. _standalone-winrepo:
  447. Managing Windows Software on a Standalone Windows Minion
  448. ========================================================
  449. The Windows Package Repository functions similar in a standalone environment,
  450. with a few differences in the configuration.
  451. To replace the winrepo runner that is used on the Salt master, an :mod:`execution module
  452. <salt.modules.win_repo>` exists to provide the same functionality to standalone
  453. minions. The functions are named the same as the ones in the runner, and are
  454. used in the same way; the only difference is that ``salt-call`` is used instead
  455. of ``salt-run``:
  456. .. code-block:: bash
  457. salt-call winrepo.update_git_repos
  458. salt-call winrepo.genrepo
  459. salt-call pkg.refresh_db
  460. After executing the previous commands the repository on the standalone system
  461. is ready to use.
  462. Custom Location for Repository SLS Files
  463. ----------------------------------------
  464. If :conf_minion:`file_roots` has not been modified in the minion
  465. configuration, then no additional configuration needs to be added to the
  466. minion configuration. The :py:func:`winrepo.genrepo
  467. <salt.modules.win_repo.genrepo>` function from the :mod:`winrepo
  468. <salt.modules.win_repo>` execution module will by default look for the
  469. filename specified by :conf_minion:`winrepo_cachefile` within
  470. ``C:\salt\srv\salt\win\repo``.
  471. If the :conf_minion:`file_roots` parameter has been modified, then
  472. :conf_minion:`winrepo_dir` must be modified to fall within that path, at the
  473. proper relative path. For example, if the ``base`` environment in
  474. :conf_minion:`file_roots` points to ``D:\foo``, and
  475. :conf_minion:`winrepo_source_dir` is ``salt://win/repo``, then
  476. :conf_minion:`winrepo_dir` must be set to ``D:\foo\win\repo`` to ensure that
  477. :py:func:`winrepo.genrepo <salt.modules.win_repo.genrepo>` puts the cachefile
  478. into right location.
  479. Configuration options for Minions 2015.8.0 and later
  480. ====================================================
  481. On newer minions (2015.8.0 and later), the :conf_minion:`winrepo_source_dir`
  482. config parameter (default: ``salt://win/repo-ng``) controls where
  483. :mod:`pkg.refresh_db <salt.modules.win_pkg.refresh_db>` looks for the software
  484. definition files that will be downloaded to the minion and used to generate the
  485. local database file (``winrepo.p``).
  486. Software package definitions are automatically refreshed if stale after
  487. :conf_minion:`winrepo_cache_expire_max`. Running a highstate normal forces the
  488. refresh of the package definition and generation of the meta database, unless
  489. the meta database is younger than :conf_minion:`winrepo_cache_expire_max`.
  490. Refreshing the package definitions can take some time, these options were
  491. introduced to allow more control of when it occurs.
  492. It's important use :py:func:`pkg.refresh_db <salt.modules.win_pkg.refresh_db>`
  493. to check for errors and ensure the latest package definition is on any minion
  494. your testing new definitions on.
  495. Configuration options for Minions before 2015.8.0
  496. =================================================
  497. On older minions (before 2015.8.0), the :conf_minion:`winrepo_source_dir`
  498. config parameter (default: ``salt://win/repo``) controls where
  499. :mod:`pkg.refresh_db <salt.modules.win_pkg.refresh_db>` looks for the cachefile
  500. (default: ``winrepo.p``). This means that the default location for the winrepo
  501. cachefile would be ``salt://win/repo/winrepo.p``. Both :conf_minion:
  502. winrepo_source_dir` and :conf_minion:`winrepo_cachefile` can be adjusted to
  503. match the actual location of this file on the Salt fileserver.
  504. If connected to a master, the minion will by default look for the winrepo
  505. cachefile (the file generated by the :mod:`winrepo.genrepo runner
  506. <salt.runners.winrepo.genrepo>`) at ``salt://win/repo/winrepo.p``. If the
  507. cachefile is in a different path on the salt fileserver, then
  508. :conf_minion:`win_repo_cachefile` will need to be updated to reflect the proper
  509. location.
  510. .. _2015-8-0-winrepo-changes:
  511. Changes in Version 2015.8.0
  512. ===========================
  513. Git repository management for the Windows Software Repository has changed
  514. in version 2015.8.0, and several master/minion config parameters have been
  515. renamed to make their naming more consistent with each other.
  516. For a list of the winrepo config options, see :ref:`here
  517. <winrepo-master-config-opts>` for master config options, and :ref:`here
  518. <winrepo-minion-config-opts>` for configuration options for masterless Windows
  519. minions.
  520. On the master, the :mod:`winrepo.update_git_repos
  521. <salt.runners.winrepo.update_git_repos>` runner has been updated to use either
  522. pygit2_ or GitPython_ to checkout the git repositories containing repo data. If
  523. pygit2_ or GitPython_ is installed, existing winrepo git checkouts should be
  524. removed after upgrading to 2015.8.0, to allow them to be checked out again by
  525. running :py:func:`winrepo.update_git_repos
  526. <salt.runners.winrepo.update_git_repos>`.
  527. If neither GitPython_ nor pygit2_ are installed, then Salt will fall back to
  528. the pre-existing behavior for :mod:`winrepo.update_git_repos
  529. <salt.runners.winrepo.update_git_repos>`, and a warning will be logged in the
  530. master log.
  531. .. note::
  532. Standalone Windows minions do not support the new GitPython_/pygit2_
  533. functionality, and will instead use the :py:func:`git.latest
  534. <salt.states.git.latest>` state to keep repositories up-to-date. More
  535. information on how to use the Windows Software Repo on a standalone minion
  536. can be found :ref:`here <standalone-winrepo>`.
  537. Config Parameters Renamed
  538. -------------------------
  539. Many of the legacy winrepo configuration parameters have changed in version 2015.8.0
  540. to make the naming more consistent. The old parameter names will still work,
  541. but a warning will be logged indicating that the old name is deprecated.
  542. Below are the parameters which have changed for version 2015.8.0:
  543. Master Config
  544. *************
  545. ======================== ================================
  546. Old Name New Name
  547. ======================== ================================
  548. win_repo :conf_master:`winrepo_dir`
  549. win_repo_mastercachefile :conf_master:`winrepo_cachefile`
  550. win_gitrepos :conf_master:`winrepo_remotes`
  551. ======================== ================================
  552. .. note::
  553. ``winrepo_cachefile`` is no longer used by 2015.8.0 and later minions, and
  554. the ``winrepo_dir`` setting is replaced by ``winrepo_dir_ng`` for 2015.8.0
  555. and later minions.
  556. See :ref:`here <winrepo-master-config-opts>` for detailed information on all
  557. master config options for the Windows Repo.
  558. Minion Config
  559. *************
  560. ======================== ================================
  561. Old Name New Name
  562. ======================== ================================
  563. win_repo :conf_minion:`winrepo_dir`
  564. win_repo_cachefile :conf_minion:`winrepo_cachefile`
  565. win_gitrepos :conf_minion:`winrepo_remotes`
  566. ======================== ================================
  567. See :ref:`here <winrepo-minion-config-opts>` for detailed information on all
  568. minion config options for the Windows Repo.
  569. pygit2_/GitPython_ Support for Maintaining Git Repos
  570. ----------------------------------------------------
  571. The :py:func:`winrepo.update_git_repos <salt.runners.winrepo.update_git_repos>`
  572. runner (and the corresponding :py:func:`remote execution function
  573. <salt.modules.win_repo.update_git_repos>` for standalone minions) now makes use
  574. of the same underlying code used by the :ref:`Git Fileserver Backend
  575. <tutorial-gitfs>` and :mod:`Git External Pillar <salt.pillar.git_pillar>` to
  576. maintain and update its local clones of git repositories. If a compatible
  577. version of either pygit2_ (0.20.3 and later) or GitPython_ (0.3.0 or later) is
  578. installed, then Salt will use it instead of the old method (which invokes the
  579. :py:func:`git.latest <salt.states.git.latest>` state).
  580. .. note::
  581. If compatible versions of both pygit2_ and GitPython_ are installed, then
  582. Salt will prefer pygit2_, to override this behavior use the
  583. :conf_master:`winrepo_provider` configuration parameter:
  584. .. code-block:: yaml
  585. winrepo_provider: gitpython
  586. The :mod:`winrepo execution module <salt.modules.win_repo>` (discussed
  587. above in the :ref:`Managing Windows Software on a Standalone Windows Minion
  588. <standalone-winrepo>` section) does not yet officially support the new
  589. pygit2_/GitPython_ functionality, but if either pygit2_ or GitPython_ is
  590. installed into Salt's bundled Python then it *should* work. However, it
  591. should be considered experimental at this time.
  592. .. _pygit2: https://github.com/libgit2/pygit2
  593. .. _GitPython: https://github.com/gitpython-developers/GitPython
  594. To minimize potential issues, it is a good idea to remove any winrepo git
  595. repositories that were checked out by the old (pre-2015.8.0) winrepo code when
  596. upgrading the master to 2015.8.0 or later, and run
  597. :py:func:`winrepo.update_git_repos <salt.runners.winrepo.update_git_repos>` to
  598. clone them anew after the master is started.
  599. Additional added features include the ability to access authenticated git
  600. repositories (**NOTE:** pygit2_ only), and to set per-remote config settings.
  601. An example of this would be the following:
  602. .. code-block:: yaml
  603. winrepo_remotes:
  604. - https://github.com/saltstack/salt-winrepo.git
  605. - git@github.com:myuser/myrepo.git:
  606. - pubkey: /path/to/key.pub
  607. - privkey: /path/to/key
  608. - passphrase: myaw3s0m3pa$$phr4$3
  609. - https://github.com/myuser/privaterepo.git:
  610. - user: mygithubuser
  611. - password: CorrectHorseBatteryStaple
  612. .. note::
  613. Per-remote configuration settings work in the same fashion as they do in
  614. gitfs, with global parameters being overridden by their per-remote
  615. counterparts (for instance, setting :conf_master:`winrepo_passphrase` would
  616. set a global passphrase for winrepo that would apply to all SSH-based
  617. remotes, unless overridden by a ``passphrase`` per-remote parameter).
  618. See :ref:`here <gitfs-per-remote-config>` for more a more in-depth
  619. explanation of how per-remote configuration works in gitfs, the same
  620. principles apply to winrepo.
  621. There are a couple other changes in how Salt manages git repos using
  622. pygit2_/GitPython_. First of all, a ``clean`` argument has been added to the
  623. :py:func:`winrepo.update_git_repos <salt.runners.winrepo.update_git_repos>`
  624. runner, which (if set to ``True``) will tell the runner to dispose of
  625. directories under the :conf_master:`winrepo_dir` which are not explicitly
  626. configured. This prevents the need to manually remove these directories when a
  627. repo is removed from the config file. To clean these old directories, just pass
  628. ``clean=True``, like so:
  629. .. code-block:: bash
  630. salt-run winrepo.update_git_repos clean=True
  631. However, if a mix of git and non-git Windows Repo definition files are being
  632. used, then this should *not* be used, as it will remove the directories
  633. containing non-git definitions.
  634. The other major change is that collisions between repo names are now detected,
  635. and the :py:func:`winrepo.update_git_repos
  636. <salt.runners.winrepo.update_git_repos>` runner will not proceed if any are
  637. detected. Consider the following configuration:
  638. .. code-block:: yaml
  639. winrepo_remotes:
  640. - https://foo.com/bar/baz.git
  641. - https://mydomain.tld/baz.git
  642. - https://github.com/foobar/baz
  643. The :py:func:`winrepo.update_git_repos <salt.runners.winrepo.update_git_repos>`
  644. runner will refuse to update repos here, as all three of these repos would be
  645. checked out to the same directory. To work around this, a per-remote parameter
  646. called ``name`` can be used to resolve these conflicts:
  647. .. code-block:: yaml
  648. winrepo_remotes:
  649. - https://foo.com/bar/baz.git
  650. - https://mydomain.tld/baz.git:
  651. - name: baz_junior
  652. - https://github.com/foobar/baz:
  653. - name: baz_the_third
  654. .. _wiki: https://wpkg.org/Category:Silent_Installers
  655. Troubleshooting
  656. ===============
  657. Incorrect name/version
  658. ----------------------
  659. If the package seems to install properly, but salt reports a failure then it is
  660. likely you have a version or ``full_name`` mismatch.
  661. Check the exact ``full_name`` and version used by the package. Use
  662. ``pkg.list_pkgs`` to check that the names and version exactly match what is
  663. installed.
  664. Changes to sls files not being picked up
  665. ----------------------------------------
  666. Ensure you have (re)generated the repository cache file (for older minions) and
  667. then updated the repository cache on the relevant minions:
  668. .. code-block:: bash
  669. salt-run winrepo.genrepo
  670. salt winminion pkg.refresh_db
  671. Packages management under Windows 2003
  672. --------------------------------------
  673. On Windows server 2003, you need to install optional Windows component "wmi
  674. Windows installer provider" to have full list of installed packages. If you
  675. don't have this, salt-minion can't report some installed software.
  676. How Success and Failure are Reported
  677. ------------------------------------
  678. The install state/module function of the Windows package manager works roughly
  679. as follows:
  680. 1. Execute ``pkg.list_pkgs`` and store the result
  681. 2. Check if any action needs to be taken. (i.e. compare required package
  682. and version against ``pkg.list_pkgs`` results)
  683. 3. If so, run the installer command.
  684. 4. Execute ``pkg.list_pkgs`` and compare to the result stored from
  685. before installation.
  686. 5. Success/Failure/Changes will be reported based on the differences
  687. between the original and final ``pkg.list_pkgs`` results.
  688. If there are any problems in using the package manager it is likely due to the
  689. data in your sls files not matching the difference between the pre and post
  690. ``pkg.list_pkgs`` results.