├── .gitattributes ├── .github ├── ISSUE_TEMPLATE │ ├── existing-doc-needs-improvement.md │ ├── new-doc-request.md │ └── other-bug-report.md ├── dco.yml └── workflows │ └── lint.yml ├── .gitignore ├── .licensing ├── aaronbartell.md ├── commits │ ├── NattyNarwhal.txt │ ├── aaronbartell.txt │ ├── friedkiwi.txt │ ├── jbh.txt │ ├── jkyeung.txt │ ├── jwoehr.txt │ ├── phpdave.txt │ └── worksofliam.txt ├── friedkiwi.md ├── jbh.md ├── jkyeung.md ├── jwoehr.md ├── nattynarwhal.md ├── relicense-template-cc0.txt └── worksofliam.md ├── .markdownlint.json ├── .readthedocs.yml ├── LICENSE ├── Makefile ├── README.md ├── acscloner └── README.md ├── apache └── README.md ├── camel └── README.md ├── certbot.md ├── conf.py ├── java ├── APP_SERVERS.md ├── JAVA11_EARLY_ACCESS.md ├── README.md ├── tomcat │ └── DEPLOYMENT.md └── wildfly │ └── DEPLOYMENT.md ├── kafka ├── KAFKA_CAMEL_DTAQ.md ├── KAFKA_CONNECT_JDBC.md └── README.md ├── make.bat ├── mariadb ├── MIGRATION-10.6.md └── README.md ├── nginx └── README.md ├── nodejs ├── KNOWN-ISSUES.md └── README.md ├── odbc ├── README.md ├── examples.md ├── installation.md ├── using.md └── why-odbc.md ├── porting ├── GOTCHAS.md ├── PASE-TO-AIX-LEVEL.md └── README.md ├── postgresql.md ├── python ├── INSTALLING_PYTHON_PKGS.md └── README.md ├── requirements.txt ├── tls └── README.md ├── troubleshooting ├── 5733OPS_MIGRATION.md ├── README.md ├── SETTING_BASH.md ├── SETTING_PATH.md └── YUM.md ├── user_setup └── README.md └── yum ├── 3RD_PARTY_REPOS.md ├── IBM_REPOS.md ├── OPENSSL3_MIGRATION.md └── README.md /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto 2 | 3 | *.md text 4 | Makefile binary 5 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/existing-doc-needs-improvement.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Existing documentation needs improvement 3 | about: When an existing documentation could use better explanation, setup steps, clarity, etc. 4 | title: "[Fixup]" 5 | labels: enhancement 6 | assignees: '' 7 | 8 | --- 9 | 10 | ### What example(s) need improvement? 11 | 12 | 13 | ### What improvement(s) could be made? 14 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/new-doc-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: New Documentation Request 3 | about: When there is no documentation to help with performing a certain task 4 | title: "[New]" 5 | labels: enhancement 6 | assignees: '' 7 | 8 | --- 9 | 10 | ### What documentation would you like added? 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/other-bug-report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report Bug with Documentation 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | 17 | 18 | 19 | 20 | 21 | 22 | **Describe the bug** 23 | A clear and concise description of what the bug is. 24 | 25 | **To Reproduce** 26 | Steps to reproduce the behavior: 27 | 28 | **Expected behavior** 29 | A clear and concise description of what you expected to happen. 30 | 31 | **Screenshots** 32 | If applicable, add screenshots to help explain your problem. 33 | 34 | **Additional context** 35 | Add any other context about the problem here. 36 | -------------------------------------------------------------------------------- /.github/dco.yml: -------------------------------------------------------------------------------- 1 | require: 2 | members: false 3 | -------------------------------------------------------------------------------- /.github/workflows/lint.yml: -------------------------------------------------------------------------------- 1 | name: Lint Files 2 | 3 | on: 4 | push: 5 | branches: master 6 | pull_request: 7 | branches: master 8 | workflow_dispatch: 9 | 10 | jobs: 11 | line_endings: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v1 15 | - name: Check line endings 16 | run: | 17 | ! (find . -name \*.md | xargs file | grep CRLF) 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | _build 2 | .DS_Store 3 | .venv 4 | -------------------------------------------------------------------------------- /.licensing/aaronbartell.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by Aaron Bartell 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "aaronbartell", with 10 | commit author "Aaron Bartell", are copyright of Aaron Bartell. 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | Aaron Bartell 15 | 2020/07/21 16 | -------------------------------------------------------------------------------- /.licensing/commits/NattyNarwhal.txt: -------------------------------------------------------------------------------- 1 | 14) 2 | 7f4889e188b15aed95cba551aaca446b2787e3fa More issues with build you could run into 3 | 8) 4 | -------------------------------------------------------------------------------- /.licensing/commits/aaronbartell.txt: -------------------------------------------------------------------------------- 1 | 0fef67362357657be854ec33e34c0aceb4b61241 Adding reverse proxy example. 2 | 9662a343772722821709e3a6f1b2d6b2e3903f1b Added Nginx link to docs/nginx.md folder 3 | f686731d3e59e7350d100c216cb8d57b8e69622b nginx.md edited online with Bitbucket 4 | 131df8e73cb8f88929953222587fdf0730da8f48 nginx.md created, with initial tutorial 5 | 924336b76d8be5eec2007ed6453d7f57598c1965 Added ILE langs to the README.md description. 6 | 613acc499d88b2c87345c957264f166b1d09089a Modifying Node.js install instructions so they are accurate. 7 | 8d49b696fe8981332fccc13cfea5e6b70182be0c added Getting Started. Added markdown 8 | 369f41d47b95be189f0d74f53567fb022b97602c README.md edited online with Bitbucket 9 | e687bd0e41a7ef4bb59e1472669be22a4c5e3dac README.md edited online with Bitbucket 10 | 7dca8b373fe09eb21490ae04103d168f12767e05 README.md created online with Bitbucket 11 | 2c6ef7aa37435bcaf871cba3a45c5e1c89fcf513 README.md edited online with Bitbucket 12 | 3c1692c4f84a937a252045cd5025085e672ab190 README.md edited online with Bitbucket 13 | 1) 14 | 95c7ad9f05edcbe762eb2c2ff23ff0e7da1d1ad2 README.md edited online with Bitbucket 15 | 97c5b3a68fa51196b9b51c01fc82bde9e325f867 README.md edited online with Bitbucket 16 | 5c390dd7349bf3814a260b098c04f7d6bedbd328 README.md edited online with Bitbucket 17 | 41aafb08f77d81eef8162ce63f4eb191acbee324 README.md edited online with Bitbucket 18 | 84a02bcf42b4e75da83a441217e3e6e8830b46a6 README.md edited online with Bitbucket 19 | f56416bfcbff0768c6bd0454563ec7b4e8485c74 README.md edited online with Bitbucket 20 | 5b6a99eb19330cf23514c35edc00c4f9bcd4418d README.md edited online with Bitbucket 21 | 5290643b7533bb443fab99913631173d0c5f5966 README.md edited online with Bitbucket 22 | f7c5e974df9b2119debbc75c93c022ff201396c5 Initial commit 23 | -------------------------------------------------------------------------------- /.licensing/commits/friedkiwi.txt: -------------------------------------------------------------------------------- 1 | 6) 2 | 1d551628b3cb464a14e13d70d71329b7ce613431 3RD_PARTY_REPOS.md edited online with Bitbucket 3 | -------------------------------------------------------------------------------- /.licensing/commits/jbh.txt: -------------------------------------------------------------------------------- 1 | 9) 2 | d1787f47715528d8b69b53d533a97077beeb0e25 Add SoBored repo to 3RD_PARTY_REPOS.md 3 | 18f03f3908490fa83552d9c50564b9b417e0ed08 Update without ACS title to be more clear. 4 | -------------------------------------------------------------------------------- /.licensing/commits/jkyeung.txt: -------------------------------------------------------------------------------- 1 | 12) 2 | 4cc614984bd9c32db787f2135378c51250607526 5733OPS_MIGRATION.md edited online with Bitbucket 3 | -------------------------------------------------------------------------------- /.licensing/commits/jwoehr.txt: -------------------------------------------------------------------------------- 1 | 10) 2 | 3be32840bb8fb4c296dcbc55f3cb78806d8e3a4f 3RD_PARTY_REPOS.md edited online with Bitbucket 3 | -------------------------------------------------------------------------------- /.licensing/commits/phpdave.txt: -------------------------------------------------------------------------------- 1 | 2) 2 | 2f665230f0e560f90a38330ae4791a2a09402a7f README.md edited online with Bitbucket to add Offline Install Instructions/ No FTP allowed from IBM i 3 | -------------------------------------------------------------------------------- /.licensing/commits/worksofliam.txt: -------------------------------------------------------------------------------- 1 | a31bbad730f1c121e19d31f5c8bd814c3daa939f README.md edited with description for Relic 2 | -------------------------------------------------------------------------------- /.licensing/friedkiwi.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by Yvan Janssens (@friedkiwi on Github) 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "friedkiwi", with 10 | commit author "Yvan Janssens", are copyright of Yvan Janssens . 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | Yvan Janssens 15 | 2020/10/16 16 | -------------------------------------------------------------------------------- /.licensing/jbh.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by Josh Hall 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "jbh", with 10 | commit author "Josh Hall", are copyright of Josh Hall. 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | Josh Hall 15 | 2020/07/20 16 | -------------------------------------------------------------------------------- /.licensing/jkyeung.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by John Yeung 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "jkyeung", with 10 | commit author "John Yeung", are copyright of John Yeung. 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | John Yeung 15 | 2020/07/23 16 | -------------------------------------------------------------------------------- /.licensing/jwoehr.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by Jack Woehr 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "jwoehr", with 10 | commit author "Jack Woehr", are copyright of Jack Woehr . 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | Jack Woehr 15 | 2020-07-21 16 | -------------------------------------------------------------------------------- /.licensing/nattynarwhal.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by Calvin Buckley 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "NattyNarwhal", with 10 | commit author "Calvin Buckley", are copyright of Calvin Buckley. 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | Calvin Buckley 15 | 2020/07/22 16 | -------------------------------------------------------------------------------- /.licensing/relicense-template-cc0.txt: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by {{ name of company / name of individual }} 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "{{github username}}", with 10 | commit author "{{github commit author}}", are copyright of {{ name }} . 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | {{ Full Name }} 15 | {{ creation date of document (format: yyyy/mm/dd) }} 16 | -------------------------------------------------------------------------------- /.licensing/worksofliam.md: -------------------------------------------------------------------------------- 1 | # Permission to Relicense under CC0 2 | 3 | This is a statement by Liam Allan (@worksofliam on Github) 4 | that grants permission to relicense its copyrights on documents in the 5 | [ibmi-oss-docs](https://github.com/IBM/ibmi-oss-docs) and 6 | [ibmi/opensource](https://bitbucket.org/ibmi/opensource) repositories under the 7 | Creative Commons "No Rights Reserved" license (CC0). 8 | 9 | A portion of the commits made by the Github handle "worksofliam", with 10 | commit author "Liam Allan", are copyright of Liam Allan. 11 | This document hereby grants IBM to relicense all past and present contributions 12 | of the author listed above. 13 | 14 | Liam Allan 15 | 2020/11/10 16 | -------------------------------------------------------------------------------- /.markdownlint.json: -------------------------------------------------------------------------------- 1 | { 2 | "MD013": { 3 | "code_blocks": false, 4 | "headings": false 5 | }, 6 | "MD026": { 7 | "punctuation": ".,;:!。，；：！" 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 2 | version: 2 3 | 4 | build: 5 | os: ubuntu-22.04 6 | tools: 7 | python: "3.11" 8 | 9 | sphinx: 10 | configuration: conf.py 11 | # Need to fix warnings before we can enable this 12 | #fail_on_warning: true 13 | 14 | python: 15 | install: 16 | - requirements: requirements.txt 17 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # IBM i Open Source 2 | 3 | This repo will act as the authoritative documentation location for all things 4 | IBM i Open Source Software including PASE (Yum, Node.js/Python/Ruby/PHP, ssh 5 | etc) and all native ILE languages (C,RPG,CL etc). If you see a mistake or see a 6 | way to make some of the docs better then please issue a pull request. 7 | 8 | **What if I would like to contribute (or suggest changes) to this documentation?** 9 | 10 | This documentation is open source! Please feel free to help this documentation 11 | grow in terms of volume and usability! If you would like to see changes in this 12 | documentation, please do one of the following: 13 | 14 | 1. [Submit an issue](https://github.com/IBM/ibmi-oss-docs/issues/new/choose) with the 15 | proposed changes. Please be as detailed as possible and include as much in 16 | "publishable" form as you can. 17 | 18 | 2. If you feel comfortable doing so, send a pull request. Start by forking the 19 | project, making your changes, and following the instructions 20 | [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). 21 | 22 | ## Contents 23 | 24 | ```{toctree} 25 | :maxdepth: 1 26 | 27 | Getting Started 28 | Setting up a User's Environment (SSH) 29 | Troubleshooting 30 | Node.js 31 | Python 32 | Setting up TLS 33 | ODBC 34 | Java 35 | Kafka 36 | Camel 37 | Nginx 38 | Apache 39 | PostgreSQL 40 | MariaDB 41 | Certbot (LetsEncrypt) 42 | ACS Clone Repo Tool 43 | OpenSSL 3 Migration 44 | IBM Repos 45 | Third Party Repos 46 | Porting Software to PASE 47 | Migrating from 5733-OPS 48 | ``` 49 | 50 | ## Support 51 | 52 | - [IBM i open source support](http://ibm.biz/ibmi-oss-support) 53 | 54 | ## Collaboration 55 | 56 | - [Questions/comments about this site](https://github.com/IBM/ibmi-oss-docs/issues/new/choose). 57 | - [Zulip Forum](https://chat.ibmioss.org) (replaces the Ryver forum) 58 | - [Ryver forum (Archive only)](https://ibmioss.ryver.com) 59 | 60 | 61 | ## Where to find examples 62 | 63 | - [IBM i OSS Examples (GitHub)](http://github.com/IBM/ibmi-oss-examples) 64 | 65 | ## Access to Source Code 66 | 67 | - Some open source licenses, such as GPL, require that source code necessary 68 | for building the software (including patches, build recipes, etc) be made 69 | available to the public. For these packages, the source is provided in the form 70 | of source RPMs distributed at 71 | [http://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo/src/](http://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo/src/) 72 | 73 | ## Links and other IBM i Open Source resources 74 | 75 | - [IBM i open source resources page](http://ibm.biz/ibmioss) (current) 76 | - [Previous authoritative IBMiOSS site](https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20i%20Technology%20Updates/page/Open%20Source%20Technologies) (outdated) 77 | -------------------------------------------------------------------------------- /acscloner/README.md: -------------------------------------------------------------------------------- 1 | # ACS Clone Repo Tool 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | The "Clone Repo" tool is a tool that allows you to clone any http or 8 | https-hosted RPM repository to the local Integrated File System (IFS) of the 9 | target IBM i system. 10 | 11 | ## How do I launch the "Clone Repo" tool? 12 | 13 | 1. In Access Client Solutions, first access the Open Source Package Management 14 | tool (Tools->"Open Source Package Management") 15 | 2. The clone tool is available after signing onto a system with the open source 16 | package management tool (Utilities->"Clone Repo for Offline Use") 17 | 18 | ## Interface options, explained 19 | 20 | ### Source Repository 21 | 22 | Specify the original repository that you'd like to take a clone/snapshot of. 23 | 24 | ### Destination (IFS) 25 | 26 | Specify a target directory on IBM i for the clone/snapshot. 27 | 28 | ### Additional Operations -> Create or Update Repository Definition 29 | 30 | The YUM package manager only knows about repos that are defined in YUM's 31 | repository list. The repository list is simply a set of `.repo` files in the `/QOpenSys/etc/yum/repos.d/` 32 | 33 | ### Additional Operations -> Disable Repositories that Require Internet Access from the IBM i System 34 | 35 | By default, YUM will fail any operations if it can't read from all the 36 | configured repositories. This options disables Internet-requiring repos, so that 37 | YUM operations continue to work. Keep this option checked if your IBM i system 38 | can't access the Internet. 39 | 40 | ### Additional Operations -> Create nginx configuration file 41 | 42 | Creates a configuration for the nginx http server to allow you to host this repo 43 | clone via http, so that other systems in your network can access it (more 44 | details below). 45 | 46 | ## Serving up your internal repo via nginx using ACS 47 | 48 | The ACS "Clone Repo" tool makes it easy to serve your cloned repo to other 49 | systems in your network. If you check the "create nginx configuration file" 50 | option, the following files are created for you: 51 | 52 | * nginx.conf: Used by nginx. By default, it configures nginx to use 5 worker 53 | processes and listen on port 2055. Feel free to customize to suit your needs. 54 | * startServer: Starts nginx as a background task in current subsystem. 55 | * startServerBatch: Submits nginx to QHTTPSVR subsystem (feel free to customize 56 | to suit your needs). 57 | * stopServer: Stops the nginx instance 58 | 59 | Of course, the next step is to configure other systems to point at your 60 | newly-created repo. That can be done on endpoint systems either by: 61 | 62 | 1. installing `yum-utils` and invoking `yum-config-manager --add-repo ` 63 | (for instance, `yum-config-manager --add-repo http://mysystem:2055`). 64 | 2. creating a repository definition in `/QOpenSys/etc/yum/repos.d`. A repository 65 | definition is a small text file with basic information. Use `ibm.repo` as an example. 66 | 67 | To automate yum updates, one can use a job scheduler entry, specifying `-y` so 68 | the YUM tool doesn't stop to ask for user confirmation. Example: 69 | `ADDJOBSCDE JOB(YUMUP) CMD(QSH CMD('exec /QOpenSys/pkgs/bin/yum -y upgrade')) 70 | FRQ(*WEEKLY) SCDDAY(*ALL)` 71 | This example does a daily upgrade, but note that no update will happen if the 72 | configured repo or repos have no changes. If the only configured repo is your 73 | private one, then this will not do anything until you update your repo. 74 | 75 | To summarize, the process of creating your own repository and hosting it for all 76 | your systems involves: 77 | 78 | 1. Run the ACS Clone Repo Tool, checking the "Create nginx configuration file" box 79 | 2. Start the nginx server by running the `startServer`/`startServerBatch` script 80 | 3. Configure endpoint systems 81 | 4. (optional) automate 82 | 83 | (A good practice might to to have a different repo for each class of systems, 84 | such as development, test, and production) 85 | -------------------------------------------------------------------------------- /apache/README.md: -------------------------------------------------------------------------------- 1 | # Integrating with Apache (IBM HTTP Server for i) 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Why? 8 | 9 | It is often recommended that you host web applications and APIs behind an HTTP server such 10 | as Nginx or Apache. On IBM i, Nginx is available as a PASE RPM. Apache is provided as 11 | part of the IBM HTTP Server for i (5770-DG1) product. 12 | 13 | The HTTP server can handle many things to help make your application production-ready, for 14 | instance: 15 | 16 | - queuing connections when under heavy load 17 | - Handling TLS. Note that HTTP Server for i integrates with Digital Certificate Manager (DCM), 18 | whereas Nginx does not. 19 | - Filtering various HTTP headers, etc. 20 | - Handling authentication 21 | - Serving static content (often more efficiently than a high-level language application server) 22 | - Handling multiple languages/applications behind a single virtual host 23 | - Provide logging of HTTP requests 24 | 25 | This document offers basic insight into how to tie open source workloads to Apache. It is 26 | assumed that you have a basic knowledge of some concepts. 27 | 28 | You may also want to consider using [Nginx](../nginx/README.md)! 29 | 30 | ## Technique # 1: ProxyPass directives 31 | 32 | The Apache HTTP server can serve as a simple reverse proxy to any other HTTP server, 33 | regardless of how that HTTP server is implemented. 34 | 35 | To do this, your `httpd.conf` needs to load the needed proxy modules. Unlike other platforms, 36 | which ship `.so` files (like `mod_proxy.so`), the extensions on IBM i are built in 37 | ILE service program form. 38 | 39 | ```apache 40 | LoadModule proxy_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 41 | LoadModule proxy_http_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 42 | LoadModule proxy_connect_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 43 | ``` 44 | 45 | Once those modules are loaded, you can use the `ProxyPass` and `ProxyPassReverse` directives 46 | to forward the traffic to a backend server. For instance, if you have a Python/Node.js application 47 | running on localhost port 8000, you can forward the traffic with these directives: 48 | 49 | ```apache 50 | ProxyPass / http://localhost:8000/ 51 | ProxyPassReverse / http://localhost:8000/ 52 | ``` 53 | These directives can also be used for specific paths within the website. For instance, 54 | to forward requests from within `/site`: 55 | 56 | ```apache 57 | ProxyPass /site/ http://localhost:8000/site/ 58 | ProxyPassReverse /site/ http://localhost:8000/site/ 59 | ``` 60 | 61 | When using this approach, you need to manage the backend job separately from the Apache instance. 62 | That is, a `STRTCPSVR` will not automatically start the backend jobs. Optionally, you can use 63 | [Service Commander](https://theprez.github.io/ServiceCommander-IBMi/#service-commander-for-ibm-i) 64 | for a more unified experience. 65 | 66 | Using a reverse proxy approach is generally best practice for non-PHP languages, because: 67 | - You can still leverage other open source tools to handle multiple processes if needed. Examples include: 68 | - `pm2` 69 | - `uvicorn` or `hypercorn` (Python) 70 | - `gunicorn` (Python) 71 | - You can generally choose any application server or web framework you like. There are many to choose from! 72 | Application servers that are optimized for a specific language tend to scale well. 73 | - It is relatively easy to configure and troubleshoot, even if you have little to no Apache experience. 74 | 75 | ## Technique # 2: FastCGI 76 | 77 | FastCGI in Apache is powered by the "Zend enabler." While originally written to support PHP workloads, 78 | it can work for any language that is aware of the FastCGI protocol. 79 | 80 | To use FastCGI, first load the Zend enabler module: 81 | 82 | ```apache 83 | LoadModule zend_enabler_module /QSYS.LIB/QHTTPSVR.LIB/QZFAST.SRVPGM 84 | ``` 85 | 86 | If you'd like to run under a different user ID, you can also use the `FastCGIServerID` and 87 | `ServerUserID` directives to specify an alternative profile. `ServerUserID` affects the core Apache 88 | operations (for instance, serving static files), and `FastCGIServerID` affects the processes 89 | launched by the Zend enabler. 90 | ```apache 91 | ServerUserID JGORZINS 92 | FastCGIServerID JGORZINS 93 | ``` 94 | 95 | Next, you will add a `` specification, where you add a type and handler for a particular 96 | URL path extension. In this case, I specify that all requests with a `.js` extension are handled 97 | by handler `fastcgi-script` (the Zend enabler module) with type `application/x-httpd-js` 98 | ```apache 99 | 100 | order allow,deny 101 | allow from all 102 | AddType application/x-httpd-js .js 103 | AddHandler fastcgi-script .js 104 | 105 | ``` 106 | 107 | You must also define the type in the Zend enabler modeule by way of the `fastcgi.conf` configuration file. 108 | You must specify `Server type` and `CommandLine`. You can also use `StartProcesses` to start multiple backend 109 | jobs. The `SetEnv` directive is also commonly-used. 110 | The `IpcDir` and `IpcPublic` directives are also needed for setting the behavior of UNIX Domain sockets 111 | ```lisp 112 | ; node.js server 113 | Server type="application/x-httpd-js" CommandLine="/www/myserver/htdocs/node/index.js" StartProcesses="4" SetEnv="LC_ALL=EN_US.UTF-8" 114 | ; Where to place socket files 115 | IpcDir /www/myserver/logs 116 | IpcPublic *RWX 117 | ``` 118 | 119 | You will also need to place a proper "shebang" (`#!`) line at the beginning of your script to run the proper executable. 120 | For instance, the first line of your `index.js` could be `#!/QOpenSys/pkgs/bin/node`. 121 | 122 | With FastCGI, the backend worker jobs are managed by Apache, so `STRTCPSVR` and `ENDTCPSVR` commands also 123 | start/stop the worker backend jobs as needed. 124 | 125 | FastCGI is best practice when using PHP. PHP has a long history with the FastCGI protocol, and they have evolved to work 126 | together very well. 127 | 128 | ## Technique # 3: CGI (not recommended) 129 | 130 | CGI is one of the oldest techniques for integrating code with an HTTP server. Since it just uses the standard in/out 131 | of a process to serve an HTTP request, it is truly language-agnostic. 132 | However, it is generally not recommended for use with open source languages, because: 133 | - It is inefficient (spawns a job for every request). Slow performance and high CPU usage is expected 134 | - There are very few frameworks that support CGI. Those projects, generally speaking, are "abandonware" 135 | and no longer maintained. 136 | See [this doc](http://www.youngiprofessionals.com/wiki/index.php/PASE/PASECGI), which may be out of date, for possible guidance. 137 | -------------------------------------------------------------------------------- /camel/README.md: -------------------------------------------------------------------------------- 1 | # Apache Camel 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | [Apache Camel](https://camel.apache.org) is a powerful Java-based integration framework that can be used to 8 | integrate countless technologies, including IBM i. For a brief introduction, see this article: 9 | [Integrate IBM i With Anything Using Apache Camel](https://techchannel.com/SMB/8/2021/ibm-i-apache-camel). 10 | 11 | **Examples** 12 | Examples of using Apache Camel on IBM i can be found in the IBM i OSS examples repository, in [the 'camel' directory](https://github.com/IBM/ibmi-oss-examples/tree/master/camel). 13 | 14 | ## Using the Camel JT400 Component 15 | The [JT400 Component](https://camel.apache.org/components/next/jt400-component.html) can be used to integrate 16 | with IBM i in several ways, including: 17 | - Message queues 18 | - Data queues 19 | - Program call 20 | 21 | ## Other Components 22 | Most other Apache Camel [components](https://camel.apache.org/components/next/index.html) are platform-agnostic 23 | and can be used from IBM i or to directly interact with IBM i. Some of the components most commonly used explicitly 24 | for IBM i integration include, but are not limited to: 25 | - [JDBC](https://camel.apache.org/components/next/jdbc-component.html)/[SQL](https://camel.apache.org/components/next/sql-component.html) 26 | - [Paho (mqtt/IoT)](https://camel.apache.org/components/next/paho-component.html) 27 | - [Exec (execute a command)](https://camel.apache.org/components/next/exec-component.html) 28 | - [File](https://camel.apache.org/components/next/file-component.html) 29 | - [FTP](https://camel.apache.org/components/next/ftp-component.html)/[sFTP](https://camel.apache.org/components/next/sftp-component.html) 30 | - [HTTP](https://camel.apache.org/components/next/http-component.html) 31 | - [SSH](https://camel.apache.org/components/next/ssh-component.html) 32 | -------------------------------------------------------------------------------- /certbot.md: -------------------------------------------------------------------------------- 1 | # LetsEncrypt w/Certbot 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | Certbot can be used to get/renew LetsEncrypt certificates. Follow these instructions to install and use Certbot. 8 | Certbot's web site can be found at [https://certbot.eff.org](https://certbot.eff.org). 9 | 10 | ## 1. SSH into the server 11 | 12 | SSH into the server running your HTTP website as a user with *ALLOBJ special authority. 13 | 14 | ## 2. Set up your environment 15 | 16 | It is assumed that you are running these commands from an SSH terminal. 17 | 18 | You must first assure that your PATH environment variable is set up correctly. 19 | ``` 20 | PATH=/QOpenSys/pkgs/bin:$PATH 21 | export PATH 22 | ``` 23 | 24 | ## 3. Install system dependencies 25 | 26 | Install Python 3.9 and necessary packages by running: 27 | ``` 28 | yum install python39-pip python39-cryptography 29 | ``` 30 | 31 | ## 4. Set up a Python virtual environment 32 | 33 | Execute the following instruction on the command line to set up a virtual environment. 34 | ``` 35 | python3.9 -m venv --system-site-packages /opt/certbot 36 | ``` 37 | 38 | ## 5. Install Certbot 39 | 40 | Run this command on the command line on the machine to install Certbot. 41 | ``` 42 | /opt/certbot/bin/pip install certbot 43 | ``` 44 | 45 | ## 6. Choose how you'd like to run Certbot 46 | 47 | ### Are you ok with temporarily stopping your website? 48 | #### Yes, my web server is not currently running on this machine. 49 | 50 | Stop your webserver, then run this command to get a certificate. Certbot will temporarily spin up a webserver on your machine. 51 | ``` 52 | /opt/certbot/bin/certbot certonly --standalone 53 | ``` 54 | 55 | #### No, I need to keep my web server running. 56 | 57 | If you have a webserver that's already using port 80 and don't want to stop it while Certbot runs, run this command and follow the instructions in the terminal. 58 | ``` 59 | /opt/certbot/bin/certbot certonly --webroot 60 | ``` 61 | 62 | ##### Important Note: 63 | 64 | To use the webroot plugin, your server must be configured to serve files from hidden directories. If /.well-known is treated specially by your webserver configuration, you might need to modify the configuration to ensure that files inside /.well-known/acme-challenge are served by the webserver. 65 | 66 | ## 7. Install your certificate 67 | 68 | Proper technique will vary depending on the web server in use. If using IBM i system Apache, [the DCM Tools project](https://github.com/ThePrez/DCM-tools/) may be useful. 69 | 70 | ## 8. Confirm that Certbot worked 71 | 72 | To confirm that your site is set up properly, visit https://yourwebsite.com/ in your browser and look for the lock icon in the URL bar. Most browsers will also let you inspect the certificate by clicking on the lock icon. 73 | 74 | ## 9. Renewing your certificate manually 75 | 76 | Certificate renewal can be done by running the following in your terminal: 77 | 78 | /opt/certbot/bin/certbot renew 79 | 80 | You can do a "dry run" of the renewal (making no modifications) by running: 81 | 82 | /opt/certbot/bin/certbot renew --dry-run 83 | 84 | ## 10. Setting up automatic renewal 85 | 86 | To set up automatic renewal of your certificate, first create a shell script that performs the following tasks: 87 | - Stops your web server 88 | - Runs /opt/certbot/bin/certbot renew -q 89 | - Installs the certificate 90 | - Starts your web server 91 | - (optional) Records the activity, for instance by running `system "SNDMSG MSG('Certificate renewal process complete') TOUSR(*SYSOPR)"` 92 | 93 | For instance, the following script uses [Service Commander](https://theprez.github.io/ServiceCommander-IBMi/#service-commander-for-ibm-i) to restart the app. It 94 | also writes output to `renewcert.log` and sends a message when completed. 95 | ``` 96 | #!/QOpenSys/pkgs/bin/bash 97 | export PATH=/QOpenSys/pkgs/bin:$PATH 98 | set -e 99 | cd $(dirname $0) 100 | exec >> renewcert.log 101 | exec 2>&1 102 | echo "==================================================" 103 | date 104 | sc stop mywebapp 105 | /opt/certbot/bin/certbot renew 106 | sc start mywebapp 107 | system "SNDMSG MSG('Certificate renewal process has completed') TOUSR($(/usr/bin/id -u -n))" 108 | ``` 109 | 110 | Once that is completed, you can create a job scheduler entry that calls your script. This example Shows how to create a job scheduler entry that runs at 1:11 AM on the first and third sundays. 111 | ``` 112 | ADDJOBSCDE JOB(CERTRENEW) CMD(QSH CMD('/path/to/script.sh')) FRQ(*MONTHLY) SCDDATE(*NONE) SCDDAY(*SUN) SCDTIME(011111) RELDAYMON(1 3) SAVE(*YES) 113 | ``` 114 | Replace the job name and path to script as needed. 115 | 116 | ## 11. Upgrading Certbot 117 | 118 | It's good practice to occasionally update Certbot to keep it up-to-date. To do this, run the following command on the command line on the machine. 119 | ``` 120 | /opt/certbot/bin/pip install --upgrade certbot 121 | ``` 122 | 123 | If this step leads to errors, run `rm -rf /opt/certbot` and repeat all installation instructions. 124 | 125 | 126 | 127 | ---------------------------------------------------------------------------- 128 | 129 | 130 | 131 | ## What about wildcard certificates? 132 | 133 | If you need wildcard certificates, follow steps 1-5, above, then proceed as documented here 134 | 135 | ### 6. Check if your DNS provider is supported 136 | 137 | See if your DNS provider is supported by Certbot by checking [this list in the documentation](https://certbot.eff.org/docs/using.html#dns-plugins). 138 | 139 | #### Not supported? 140 | 141 | If your DNS provider is not supported, pause here: run Certbot with the manual plugin by using [these steps from the documentation](https://certbot.eff.org/docs/using.html#manual). 142 | 143 | ##### Supported? 144 | 145 | If your DNS provider is supported, continue with the remaining instructions below in your SSH terminal. 146 | 147 | ### 7. Install correct DNS plugin 148 | 149 | Run the following command, replacing with the name of your DNS provider. 150 | ``` 151 | /opt/certbot/bin/pip install certbot-dns- 152 | ``` 153 | For example, if your DNS provider is Cloudflare, you'd run the following command: 154 | ``` 155 | /opt/certbot/bin/pip install certbot-dns-cloudflare 156 | ``` 157 | 158 | ### 8. Set up credentials 159 | 160 | You'll need to set up DNS credentials. 161 | Follow the steps in the "Credentials" section for your DNS provider to access or create the appropriate credential configuration file. Find credentials instructions for your DNS provider by clicking [the DNS plugin's name on the Documentation list](https://certbot.eff.org/docs/using.html#dns-plugins). 162 | 163 | ### 9. Get a certificate 164 | 165 | Run one of the commands in the "Examples" section of the [instructions for your DNS provider](https://certbot.eff.org/docs/using.html#dns-plugins). 166 | 167 | ### 10. Install and renew certificate 168 | 169 | Follow steps 7 and beyond, above. 170 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | import os 2 | from docutils import nodes 3 | 4 | # Configuration file for the Sphinx documentation builder. 5 | # 6 | # This file only contains a selection of the most common options. For a full 7 | # list see the documentation: 8 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 9 | 10 | # -- Path setup -------------------------------------------------------------- 11 | 12 | # If extensions (or modules to document with autodoc) are in another directory, 13 | # add these directories to sys.path here. If the directory is relative to the 14 | # documentation root, use os.path.abspath to make it absolute, like shown here. 15 | # 16 | # import os 17 | # import sys 18 | # sys.path.insert(0, os.path.abspath('.')) 19 | 20 | 21 | # -- Project information ----------------------------------------------------- 22 | 23 | project = 'IBM i OSS Docs' 24 | copyright = '2020, IBM i OSS Docs Authors' 25 | author = 'IBM i OSS Docs Authors' 26 | 27 | 28 | # -- General configuration --------------------------------------------------- 29 | 30 | # Add any Sphinx extension module names here, as strings. They can be 31 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 32 | # ones. 33 | extensions = [ 34 | 'myst_parser', 35 | 'sphinx_reredirects', 36 | ] 37 | 38 | source_suffix = { 39 | '.rst': 'restructuredtext', 40 | '.txt': 'markdown', 41 | '.md': 'markdown', 42 | } 43 | 44 | # Add any paths that contain templates here, relative to this directory. 45 | templates_path = ['_templates'] 46 | 47 | # List of patterns, relative to source directory, that match files and 48 | # directories to ignore when looking for source files. 49 | # This pattern also affects html_static_path and html_extra_path. 50 | exclude_patterns = [ 51 | '.github', 52 | '_build', 53 | 'Thumbs.db', 54 | '.DS_Store', 55 | '.licensing', 56 | 'requirements.txt', 57 | '.venv*', 58 | ] 59 | 60 | master_doc = 'README' 61 | 62 | # -- Options for HTML output ------------------------------------------------- 63 | 64 | # The theme to use for HTML and HTML Help pages. See the documentation for 65 | # a list of builtin themes. 66 | # 67 | html_theme = 'sphinx_rtd_theme' 68 | 69 | # Add any paths that contain custom static files (such as style sheets) here, 70 | # relative to this directory. They are copied after the builtin static files, 71 | # so a file named "default.css" will overwrite the builtin "default.css". 72 | html_static_path = ['_static'] 73 | 74 | redirects = { 75 | 'java11/JAVA11_EARLY_ACCESS': "../java/JAVA11_EARLY_ACCESS.html", 76 | 'yum/RELEASE_REPOS': "../yum/IBM_REPOS.html", 77 | 'index': 'README.html', 78 | } 79 | 80 | # Allow MyST to generate links to subheadings up to 3 deep (H3 / ###) 81 | myst_heading_anchors = 3 82 | -------------------------------------------------------------------------------- /java/APP_SERVERS.md: -------------------------------------------------------------------------------- 1 | # Open Source Java Application Servers 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | This page documents open source Java application servers. All items on this page are known to work on IBM i. 8 | 9 | ```{eval-rst} 10 | +--------------------------------+----------------------------------------------+---------------------------+ 11 | | Application Server | Governed By | IBM `Support`_ Available? | 12 | +================================+==============================================+===========================+ 13 | | `Apache Tomcat`_ | `The Apache Software Foundation (ASF)`_ | yes | 14 | +--------------------------------+----------------------------------------------+---------------------------+ 15 | | `Wildfly`_ | `Red Hat`_ | yes | 16 | +--------------------------------+----------------------------------------------+---------------------------+ 17 | | `OpenLiberty`_ | `IBM`_ | no | 18 | +--------------------------------+----------------------------------------------+---------------------------+ 19 | | `Eclipse Jetty`_ | `The Eclipse Foundation`_ | yes | 20 | +--------------------------------+----------------------------------------------+---------------------------+ 21 | 22 | .. _Apache Tomcat: https://tomcat.apache.org/ 23 | .. _Wildfly: https://wildfly.org/ 24 | .. _OpenLiberty: https://openliberty.io/ 25 | .. _Eclipse Jetty: https://www.eclipse.org/jetty/ 26 | .. _The Apache Software Foundation (ASF): https://apache.org 27 | .. _Red Hat: https://redhat.com 28 | .. _IBM: https://ibm.com 29 | .. _The Eclipse Foundation: https://eclipse.org 30 | .. _Support: https://ibm.biz/ibmi-oss-support 31 | ``` 32 | 33 | # Deployment Guides 34 | - [WildFly](wildfly/DEPLOYMENT.md) 35 | - [TomCat](tomcat/DEPLOYMENT.md) 36 | -------------------------------------------------------------------------------- /java/JAVA11_EARLY_ACCESS.md: -------------------------------------------------------------------------------- 1 | # Java 11 Early Access RPM 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | A Java RPM is now available, via the `openjdk-11-ea` packages! Note, however, 8 | this is not considered generally available (GA). It is an early access package ONLY. 9 | 10 | This page is here to address some frequently asked questions you may have. 11 | 12 | ## Is this Java production-ready? 13 | 14 | No! These are early access RPMs, denoted with the `-ea` suffix in the package name. 15 | 16 | ## Why is this only "early access"? 17 | 18 | Currently, this Java runtime has not yet completed all testing and is therefore 19 | not certified as production ready. We have, however, done thorough functional 20 | testing of various workloads, including Apache Camel, ActiveMQ, Tomcat, maven, 21 | Jenkins, etc. We are releasing an "early access" version to solicit feedback 22 | from the IBM i community, and we welcome your feedback for any testing you do! 23 | 24 | ## How do I install this? 25 | 26 | Simply use `yum` or the Open Source Package Management tool in 27 | Access Client Solutions to install the `openjdk-11-ea` package. 28 | 29 | ## Where does this install? 30 | 31 | The Java Runtime Environment (JRE) gets installed to `/QOpenSys/pkgs/lib/jvm/openjdk-11` 32 | 33 | ## How do I select this JVM to run my program? 34 | 35 | If invoking Java directly from the command line, you will need to fully-qualify 36 | the `java` binary (`/QOpenSys/pkgs/lib/jvm/openjdk-11/bin/java`) or add the 37 | executable's directory to the beginning of your PATH, like so: 38 | 39 | ```bash 40 | PATH=/QOpenSys/pkgs/lib/jvm/openjdk-11/bin:$PATH 41 | export PATH 42 | ``` 43 | 44 | If you'd like common Java-based tools, such as activemq or maven, to use this 45 | Java, you should also set the `JAVA_HOME` environment variable: 46 | 47 | ```bash 48 | JAVA_HOME=/QOpenSys/pkgs/lib/jvm/openjdk-11 49 | export JAVA_HOME 50 | ``` 51 | 52 | ## Why do I get error "Directory /QOpenSys/pkgs/lib/jvm/openjdk-11 in the JAVA_HOME environment variable does not contain a Java Virtual Machine."? 53 | 54 | The default java launchers do not currently accommodate this open source distribution. 55 | This will likely be investigated and addressed in a future release. In the 56 | interim, launch Java explicitly as documented in the previous section. 57 | 58 | ## Can this integrate with RPG via the *JAVA declaration? 59 | 60 | No. 61 | This will likely be investigated for a future release. 62 | 63 | ## Can I use ILE native methods? 64 | 65 | No, and there are no plans to support this. Instead, use the JTOpen (jt400) 66 | library's `ProgramCall` support. 67 | This also means that the `*CURRENT` special value cannot be used for 68 | authentication with the JTOpen library. 69 | 70 | ## Does this show up in WRKJVMJOB? 71 | 72 | No. 73 | This will likely be added in a future release. 74 | 75 | ## Can this run inside of a chroot container? 76 | 77 | Yes!! Unlike JV1 flavors of Java, this open source version is container-friendly. 78 | 79 | ## Are there any functions known not to work? 80 | 81 | As previously stated, not all testing has been completed, and this is not 82 | considered production-ready. 83 | That being said, the `sun.nio.ch.AixAsynchronousChannelProvider` class will 84 | malfunction and cause program crashes on IBM i 7.2. On IBM i 7.3, this function 85 | requires PTF SI71837. For IBM i 7.4, PTF SI72224 is required. 86 | -------------------------------------------------------------------------------- /java/README.md: -------------------------------------------------------------------------------- 1 | # Java 2 | 3 | Here you'll find information about using open source Java on IBM i. 4 | 5 | ## Contents 6 | 7 | ```{toctree} 8 | :maxdepth: 1 9 | 10 | Java 11 11 | Application Servers 12 | ``` 13 | -------------------------------------------------------------------------------- /java/tomcat/DEPLOYMENT.md: -------------------------------------------------------------------------------- 1 | # Deploying ASF TomCat on IBM i (using GitBucket as a sample application) 2 | 3 | This simple guide is intended to help you deploy your first application in TomCat standalone mode. For 4 | this exercise, we use [GitBucket](https://github.com/gitbucket/gitbucket) as a sample application. 5 | You can similarly deploy any .war file using these steps 6 | 7 | 8 | # Prerequisite setup 9 | As with any open source software, it is recommended that you use an SSH 10 | terminal session to perform these tasks. QSH or other 5250 interfaces may 11 | work, but can be problematic. 12 | 13 | ## Run bash and set appropriate environment variables 14 | These steps assume you are running with SSH and 15 | [using bash as your default shell](../../troubleshooting/SETTING_BASH.md). 16 | 17 | If you're not running `bash`, you can run it explicitly: 18 | ```bash 19 | exec /QOpenSys/pkgs/bin/bash 20 | ``` 21 | 22 | If you haven't already [customized your PATH to include open source](../../troubleshooting/SETTING_BASH.md), 23 | you can do that temporarily: 24 | ```bash 25 | export PATH=/QOpenSys/pkgs/bin:$PATH 26 | ``` 27 | ## Choose installation and download directories 28 | Save your installation and download directory in environment variables 29 | (these are only used for convenience during the steps in this guide): 30 | ```bash 31 | export DOWNLOAD=/opt/download 32 | export TOMCAT=/opt/tomcat 33 | ``` 34 | The aboves assumes the following directories: 35 | - TomCat installation directory: `/opt/tomcat` 36 | - Download directory (when downloading TomCat and GitBucket): `/opt/download` 37 | 38 | You may choose to download files or deploy TomCat anywhere on the filesystem. 39 | Just change these values accordingly. 40 | 41 | (subsequent steps assume you are using this same SSH session) 42 | 43 | 44 | ## Create installation directory and download directory 45 | ```bash 46 | mkdir -p $DOWNLOAD 47 | mkdir -p $TOMCAT 48 | ``` 49 | 50 | # Step 1: Install Required Software 51 | ```bash 52 | yum install wget tar-gnu gzip nano openjdk-11 ca-certificates-mozilla 53 | ``` 54 | 55 | Alternatively, use Access Client Solutions to install these packages. 56 | 57 | # Step 2: Download TomCat 58 | 59 | ## Technique 1: Using `wget` 60 | (change the version number, if needed, to the version you would like to install) 61 | ```bash 62 | cd $DOWNLOAD 63 | wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.0.14/bin/apache-tomcat-10.0.14.tar.gz 64 | ``` 65 | 66 | ## Technique 2: Manual download 67 | Just navigate to [the TomCat website](https://tomcat.apache.org/) and access the downloads from the navication pane 68 | Download the latest version in .tar.gz format. Once downloaded, place in the download directory chosen earlier. 69 | 70 | ![image](https://user-images.githubusercontent.com/17914061/147589739-6954c981-784b-4965-a005-9c151b69d80c.png) 71 | 72 | 73 | 74 | # Step 3: Install TomCat 75 | 76 | (change the version number in the filename, if needed, to the proper version) 77 | ```bash 78 | cd $DOWNLOAD 79 | tar --strip-components=1 -C $TOMCAT -xzvf apache-tomcat-10.0.14.tar.gz 80 | ``` 81 | 82 | # Step 4: Configure TomCat to use Java of choice 83 | Create a `setenv.sh` file located in the `/bin` directory of the TomCat installation directory. 84 | This script will be called to set any needed environment variables, and can be used to set `JAVA_HOME` 85 | to the location of our choosing. 86 | For this, you can use the editor of your choice (assuming you have a drive mapped with sshfs or NetServer), 87 | or you can use a terminal-based editor like nano: 88 | ```bash 89 | cd $TOMCAT/bin 90 | touch setenv.sh 91 | nano setenv.sh 92 | ``` 93 | Simply add the following lines (depending which Java you choose) and save the file 94 | 95 | For OpenJDK: 96 | ```bash 97 | JAVA_HOME="/QOpenSys/pkgs/lib/jvm/openjdk-11" 98 | export JAVA_HOME 99 | ``` 100 | For JV1: 101 | ```bash 102 | JAVA_HOME="/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit" 103 | export JAVA_HOME 104 | ``` 105 | 106 | # Step 5 : Configure server port (optional) 107 | By default, TomCat will listen on port 8080. To change that, open 108 | the `server.xml` file in the `conf/` directory 109 | of the TomCat installation. 110 | For this, you can use the editor of your choice (assuming you have a drive mapped with sshfs or NetServer), 111 | or you can use a terminal-based editor like nano: 112 | ```bash 113 | cd $TOMCAT/conf/ 114 | nano server.xml 115 | ``` 116 | 117 | Search for `protocol="HTTP` to find the `` tag for the HTTP protocol (in nano, this can be 118 | done with ctrl+W). You will find a section that defines which port is used. The `port` value represents 119 | the standard port, and the `redirectPort` is the target port that traffic is redirected to if TLS is required. 120 | ```xml 121 | 125 | ``` 126 | Change these values to something appropriate for your deployment. Also, add `maxPostSize="152428800" to increase 127 | the TomCat maximum file upload size (since GitBucket exceeds the default 50M limit).`For instance, the following 128 | configures the server to use port 9080 for HTTP and port 9443 for TLS: 129 | ```xml 130 | 134 | ``` 135 | If you changed the redirectPort in the previous step, you will also need to change the connector configuration 136 | for TLS. To do so, search for `protocol="org.apache.coyote` to find the `` tag for the TLS protocol 137 | ```xml 138 | 140 | 141 | 142 | 144 | 145 | 146 | ``` 147 | Change as appropriate. In this example, we've changed the `redirectPort` to 9443. For instance: 148 | ```xml 149 | 151 | 152 | 153 | 155 | 156 | 157 | ``` 158 | As you can see, this is also where you would perform the necessary TLS configuration for the server. 159 | 160 | # Step 6: Create management users (Optional, recommended) 161 | By default, no user is included in the "manager-gui" role required 162 | to operate the "/manager/html" web application. If you wish to use this app, 163 | you must define such a user in the `tomcat-users.xml` file in the `conf/` directory 164 | of the TomCat installation. 165 | Similarly, there is no user included for "manager-script" role 166 | required to access a plaintext-based management interface, and no "manager-status" 167 | role to see server status 168 | 169 | To add these users, you can use the editor of your choice (assuming you have a drive mapped with sshfs or NetServer), 170 | or you can use a terminal-based editor like nano: 171 | ```bash 172 | cd $TOMCAT/conf/ 173 | nano tomcat-users.xml 174 | ``` 175 | 176 | As an example configuration, you will find a commented-out declaration of `admin` and `root` users, for instance 177 | ```xml 178 | 182 | ``` 183 | Add the following somewhere inside the `tomcat-users` tag (and outside of a comment), but change the 184 | password value from `admin4ever` to your passwords of choosing. 185 | ```xml 186 | 187 | 188 | 189 | 190 | 191 | ``` 192 | 193 | # Step 7: Increase TomCat file upload size limit (optional) 194 | TomCat, by default, only lets you upload files that are 50M or smaller. Some large .war files 195 | are larger than this, so it is sometimes good to increase this maximum. 196 | ```bash 197 | cd $TOMCAT/webapps/manager/WEB-INF 198 | nano web.xml 199 | ``` 200 | 201 | Look for the following section: 202 | ```xml 203 | 204 | 205 | 52428800 206 | 52428800 207 | 0 208 | 209 | ``` 210 | Change the values of `max-file-size` and `max-request-size` to something larger, like `152428800`. 211 | For instance: 212 | ```xml 213 | 214 | 215 | 152428800 216 | 152428800 217 | 0 218 | 219 | ``` 220 | 221 | 222 | 223 | # Step 8: Convert GitBucket to Jakarta EE and Deploy 224 | 225 | GitBucket is built against Java EE. However, TomCat 10 (used in this guide) now uses Jakarta EE 226 | classes. See [the relevant TomCat docs](https://tomcat.apache.org/migration-10.html)) for more 227 | information. There is a TomCat migration tool available, but TomCat can also automatically 228 | convert applications on startup. To do so, place the `.war` in the `webapps-javaee` directory: 229 | 230 | ```bash 231 | cd $DOWNLOAD 232 | wget https://github.com/gitbucket/gitbucket/releases/download/4.37.1/gitbucket.war 233 | mkdir -p $TOMCAT/webapps-javaee 234 | cp gitbucket.war $TOMCAT/webapps-javaee 235 | ``` 236 | 237 | # Step 9: Start TomCat 238 | ```bash 239 | cd $TOMCAT/bin 240 | ./startup.sh 241 | ``` 242 | You're done!! At this point: 243 | - Tomcat should now be running at `http://:8080` (or whatever port you've chosen earlier). 244 | - GitBucket should now be running at `http://:8080/gitbucket` (or whatever port you've chosen earlier) 245 | 246 | 247 | You can deploy other applications through the management interface by doing the following steps: 248 | - Open your browser to `http://:8080/` 249 | - Click the "Manager App" button (log in with `admin` and the password you created earlier) 250 | ![image](https://user-images.githubusercontent.com/17914061/147600657-28dacbc2-be14-459d-ac7f-0f84170497ba.png) 251 | 252 | - Scroll down to the "Deploy" section and go to "WAR file to deploy". Browse for your `gitbucket.war` file and 253 | click "Deploy" 254 | ![image](https://user-images.githubusercontent.com/17914061/147600763-4f7f8faf-46ec-4c14-8f7b-0754a13c89e7.png) 255 | 256 | - You should now see your application in the deployed application list and can start/stop/etc through this interface. 257 | 258 | # Step 10: Managing with Service Commander (optional) 259 | You can elect to manage your WildFly instance with Service Commander. If you are unfamiliar with Service Commander, 260 | you can read more [here](https://theprez.github.io/ServiceCommander-IBMi/#service-commander-for-ibm-i). 261 | The steps to leverage this tool include: 262 | - Install the `service-commander` package: 263 | ```yum 264 | yum install service-commander 265 | ``` 266 | 267 | - `cd` into your installation's `bin/` directory: 268 | ```bash 269 | cd $TOMCAT/bin 270 | ``` 271 | 272 | - Run the `scinit` command to create a service definition for the `startup.sh` command. Proceed to answer 273 | the questions as in the following screenshot, except use the port number you chose earlier (and feel free to 274 | use name as you wish). 275 | If you configured the server addresses in step 5: 276 | ```bash 277 | scinit ./startup.sh 278 | ``` 279 | ![image](https://user-images.githubusercontent.com/17914061/147699367-ab8eef45-4103-450a-9162-de8030c2edfc.png) 280 | 281 | It should also print information about where it stored the service definition 282 | ![image](https://user-images.githubusercontent.com/17914061/147699504-84de2cd8-85bc-4452-bb45-e13483a80a24.png) 283 | 284 | Now, you can use the `sc` command to start, stop, or check on your WildFly instance. Examples: 285 | ![image](https://user-images.githubusercontent.com/17914061/147699566-29274c08-49b2-4416-81e0-246c7a92144d.png) 286 | 287 | 288 | -------------------------------------------------------------------------------- /java/wildfly/DEPLOYMENT.md: -------------------------------------------------------------------------------- 1 | # Deploying WildFly on IBM i (using GitBucket as a sample application) 2 | 3 | This simple guide is intended to help you deploy your first application in WildFly standalone mode. For 4 | this exercise, we use [GitBucket](https://github.com/gitbucket/gitbucket) as a sample application. 5 | You can similarly deploy any .war file using these steps 6 | 7 | 8 | # Prerequisite setup 9 | As with any open source software, it is recommended that you use an SSH 10 | terminal session to perform these tasks. QSH or other 5250 interfaces may 11 | work, but can be problematic. 12 | 13 | ## Run bash and set appropriate environment variables 14 | These steps assume you are running with SSH and 15 | [using bash as your default shell](../../troubleshooting/SETTING_BASH.md). 16 | 17 | If you're not running `bash`, you can run it explicitly: 18 | ```bash 19 | exec /QOpenSys/pkgs/bin/bash 20 | ``` 21 | 22 | If you haven't already [customized your PATH to include open source](../../troubleshooting/SETTING_BASH.md), 23 | you can do that temporarily: 24 | ```bash 25 | export PATH=/QOpenSys/pkgs/bin:$PATH 26 | ``` 27 | ## Choose installation and download directories 28 | Save your installation and download directory in environment variables 29 | (these are only used for convenience during the steps in this guide): 30 | ```bash 31 | export DOWNLOAD=/opt/download 32 | export WILDFLY=/opt/wildfly 33 | ``` 34 | The aboves assumes the following directories: 35 | - WildFly installation directory: `/opt/wildfly` 36 | - Download directory (when downloading WildFly and GitBucket): `/opt/download` 37 | 38 | You may choose to download files or deploy WildFly anywhere on the filesystem. 39 | Just change these values accordingly. 40 | 41 | (subsequent steps assume you are using this same SSH session) 42 | 43 | 44 | ## Create installation directory and download directory 45 | ```bash 46 | mkdir -p $DOWNLOAD 47 | mkdir -p $WILDFLY 48 | ``` 49 | 50 | # Step 1: Install Required Software 51 | ```bash 52 | yum install wget tar-gnu gzip nano openjdk-11 53 | ``` 54 | 55 | Alternatively, use Access Client Solutions to install these packages. 56 | 57 | # Step 2: Download WildFly 58 | 59 | ## Technique 1: Using `wget` 60 | (change the version number, if needed, to the version you would like to install) 61 | ```bash 62 | cd $DOWNLOAD 63 | wget https://github.com/wildfly/wildfly/releases/download/28.0.0.Final/wildfly-28.0.0.Final.tar.gz 64 | ``` 65 | 66 | ## Technique 2: Manual download 67 | Just navigate to [the WildFly website](https://www.wildfly.org/downloads/) and access the downloads. 68 | Download the latest version in .tar.gz format. Once downloaded, place in the download directory chosen earlier. 69 | ![image](https://user-images.githubusercontent.com/17914061/146617098-cbd084eb-4529-47ee-b226-cf9bf3f837d3.png) 70 | 71 | 72 | # Step 3: Install WildFly 73 | 74 | (change the version number in the filename, if needed, to the proper version) 75 | ```bash 76 | cd $DOWNLOAD 77 | tar --strip-components=1 -C $WILDFLY -xzvf wildfly-28.0.0.Final.tar.gz 78 | ``` 79 | 80 | # Step 4: Configure WildFly to use Java of choice 81 | Open the `standalone.conf` file located in the `/bin` directory of the WildFly installation directory. 82 | For this, you can use the editor of your choice (assuming you have a drive mapped with sshfs or NetServer), 83 | or you can use a terminal-based editor like nano: 84 | ```bash 85 | cd $WILDFLY/bin 86 | nano standalone.conf 87 | ``` 88 | The default `standalone.conf` file has a commented-out line with a `JAVA_HOME` value. Uncomment the line and 89 | insert the appropriate JAVA_HOME value. You can choose between OpenJDK or JV1 versions of Java. 90 | 91 | For OpenJDK: 92 | ```bash 93 | JAVA_HOME="/QOpenSys/pkgs/lib/jvm/openjdk-11" 94 | ``` 95 | For JV1: 96 | ```bash 97 | JAVA_HOME="/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit" 98 | ``` 99 | 100 | # Step 5 : Configure server address (optional) 101 | This step is recommended so that WildFly's default behavior is to bind to the correct addresses. If you do 102 | not do this step, you will need to specify the addresses on the command line later when you start WildFly. 103 | 104 | Open the `standalone.xml` file in the `standalone/configuration` directory 105 | of the WildFly installation directory. 106 | For this, you can use the editor of your choice (assuming you have a drive mapped with sshfs or NetServer), 107 | or you can use a terminal-based editor like nano: 108 | ```bash 109 | cd $WILDFLY/standalone/configuration/ 110 | nano standalone.xml 111 | ``` 112 | 113 | Search for the `` tag (in nano, this can be done with ctrl+W). You will find a section that defines 114 | the management and public interfaces. Note that there are other tags that mention "interfaces" but here you only 115 | need to find the specific `` section. 116 | ```xml 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | ``` 125 | Change these values to something appropriate for your deployment. For instance, the following 126 | configures the management interfaces to use `0.0.0.0` (listens on any address), and it 127 | configures the public interface (used for web applications) to the IP address of the IBM i 128 | system. In the default configuration, these interfaces are only accessible from the local system. 129 | ```xml 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | ``` 138 | 139 | # Step 6: Create a management user 140 | First, set `JAVA_HOME` to the value you configured in `standalone.conf`: 141 | ```bash 142 | export JAVA_HOME=/QOpenSys/pkgs/lib/jvm/openjdk-11 143 | ``` 144 | or.... 145 | ```bash 146 | export JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit 147 | ``` 148 | Then run the `add-user.sh` script 149 | ```bash 150 | cd $WILDFLY/bin 151 | ./add-user.sh 152 | ``` 153 | Follow these steps: 154 | - When it asks, "What type of user do you wish to add?", enter "a" for management user 155 | - For "Username", enter `admin` 156 | - Enter `a` to choose "a) Update the existing user password and roles" 157 | - Follow the remaining prompts to choose a password. Just press [enter] to accept the defaults for all other questions. 158 | 159 | # Step 7: (optional) Deploy GitBucket by downloading and placing in deployments directory 160 | If you skip this step, you can deploy GitBucket through WildFly's management interface later 161 | 162 | ```bash 163 | cd $DOWNLOAD 164 | wget https://github.com/gitbucket/gitbucket/releases/download/4.37.1/gitbucket.war 165 | cp gitbucket.war $WILDFLY/standalone/deployments 166 | ``` 167 | Alternatively, manually download the latest `gitbucket.war` and place in the `standalone/deployments` directory. 168 | 169 | Now, the GitBucket application will be deployed when WildFly is started. 170 | 171 | # Step 8: Start WildFly 172 | 173 | If you configured the server addresses in step 5, you can now start WildFly 174 | in standalone mode by doing the following: 175 | ```bash 176 | cd $WILDFLY/bin 177 | ./standalone.sh 178 | ``` 179 | If you did not configure the server addresses, you may specify them on the command-line 180 | invocation of `standalone.sh` using the `-b` and `-bmanagement` arguments, for instance: 181 | ```bash 182 | cd $WILDFLY/bin 183 | ./standalone.sh -b 171.20.0.10 -bmanagement 0.0.0.0 184 | ``` 185 | 186 | You're done!! At this point: 187 | - The management interface will be running at `http://:9990/` (log in with `admin` and the password you created earlier) 188 | - If you deployed GitBucket in Step 7, it will be running at `http://:8080/gitbucket` 189 | 190 | If you didn't deploy GitBucket, you can do so through the management interface by doing the following steps: 191 | - Download the latest release of GitBucket from [their releases page on GitHub](https://github.com/gitbucket/gitbucket/releases) (in the form of `gitbucket.war`) to your PC 192 | - Open your browser to `http://:9990/` (log in with `admin` and the password you created earlier) 193 | - Click the "Deployments" tab or the "Deployments" link on the homepage 194 | ![image](https://user-images.githubusercontent.com/17914061/146619131-3d0d811b-c9fe-4a81-8d80-174c9d7f2a08.png) 195 | 196 | - Click the action button in the left sidebar and choose "Upload Deployment" 197 | ![image](https://user-images.githubusercontent.com/17914061/146619197-a7b70846-def2-4330-a6a2-fc370a99276f.png) 198 | 199 | - Follow the prompts to upload `gitbucket.war` from your PC and specify application names 200 | ![image](https://user-images.githubusercontent.com/17914061/146619462-6b254efd-d997-4c10-a731-d6ba78969201.png) 201 | 202 | - On success, it should show upload complete 203 | ![image](https://user-images.githubusercontent.com/17914061/146619338-69424a55-6695-4536-858d-6a1f39a8d84f.png) 204 | 205 | - Once deployed, it will show up in deployments and you can manage through the management console 206 | ![image](https://user-images.githubusercontent.com/17914061/146620666-63c8004a-ddd4-4460-8f36-bdd605b19d42.png) 207 | 208 | # You should now be running GitBucket with WildFly! 209 | ![image](https://user-images.githubusercontent.com/17914061/146620767-e7d2487f-704f-48c4-8125-5836c98bb698.png) 210 | 211 | 212 | # Managing with Service Commander (optional) 213 | You can elect to manage your WildFly instance with Service Commander. If you are unfamiliar with Service Commander, 214 | you can read more [here](https://theprez.github.io/ServiceCommander-IBMi/#service-commander-for-ibm-i). 215 | The steps to leverage this tool include: 216 | - Install the `service-commander` package: 217 | ```yum 218 | yum install service-commander 219 | ``` 220 | 221 | - `cd` into your installation's `bin/` directory: 222 | ```bash 223 | cd $WILDFLY/bin 224 | ``` 225 | 226 | - Run the `scinit` command to create a service definition for the `standalone.sh` command. Proceed to answer 227 | the questions as in the following screenshot. 228 | If you configured the server addresses in step 5: 229 | ```bash 230 | scinit ./standalone.sh 231 | ``` 232 | If you did not configure the server addresses, you may specify them on the command-line 233 | invocation using the `-b` and `-bmanagement` arguments, for instance: 234 | ```bash 235 | scinit ./standalone.sh -b 171.20.0.10 -bmanagement 0.0.0.0 236 | ``` 237 | 238 | ![image](https://user-images.githubusercontent.com/17914061/146621112-a152d72d-f6eb-4733-8c55-2b38a9907d36.png) 239 | It should also print information about where it stored the service definition 240 | ![image](https://user-images.githubusercontent.com/17914061/146621169-9c0eef0a-9fcf-47a2-89fd-be48cf349195.png) 241 | 242 | Now, you can use the `sc` command to start, stop, or check on your WildFly instance. Examples: 243 | ![image](https://user-images.githubusercontent.com/17914061/146621332-d2578c15-ef90-4887-8188-6bfe59d3a2d7.png) 244 | 245 | 246 | 247 | -------------------------------------------------------------------------------- /kafka/KAFKA_CAMEL_DTAQ.md: -------------------------------------------------------------------------------- 1 | # Using Db2 Triggers and Apache Camel to stream Db2 events to Kafka 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## How it works 8 | 9 | ## How to implement 10 | IBM and Perforce ran a workshop for the FOCUS2020 event, the source code and steps for which can be found [here](https://github.com/ThePrez/FOCUS2020-Workshop/). 11 | You can follow those workshop steps on your own development system and examine the code for a more thorough understanding. The general steps are outlined here 12 | 13 | ### Step 1: Create a data queue 14 | For instance 15 | ```fortran 16 | CRTDTAQ DTAQ(MYLIB/MYDQ) MAXLEN(64000) SENDERID(*YES) SIZE(*MAX2GB) TEXT('row level changes for MYLIB/MYTABLE') 17 | ``` 18 | ### Step 2: Create a Db2 trigger 19 | An example can be found in the above workshop, or [here](https://github.com/IBM/ibmi-oss-examples/blob/master/camel/dtaq_to_kafka/banking_kafka_example.sql). 20 | The key points are that the transaction is converted to JSON and sent to the data queue via `qsys2.send_data_queue_utf8()` 21 | 22 | ### Step 3: Create a Camel route 23 | Information about writing and deploying a Camel route can be found in the above workshop, or [here](https://github.com/IBM/ibmi-oss-examples/tree/master/camel). 24 | A simple route to stream information from the data queue to Kafka looks like this: 25 | ```java 26 | from(dtaqUri) 27 | .convertBodyTo(String.class, "UTF-8") // We do this to convert the bytes from the data queue (UTF-8 JSON data) into a String object in the message 28 | .to(kafkaUri); 29 | ``` 30 | -------------------------------------------------------------------------------- /kafka/KAFKA_CONNECT_JDBC.md: -------------------------------------------------------------------------------- 1 | # Using the JDBC Source/Sink Connectors and Kafka Connect 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | Download the JDBC Connector (Source and Sink) from Confluent Hub [confluentinc-kafka-connect-jdbc-10.2.0.zip]. Source connectors are used to read data from a database. Sink connectors are used to insert data into a database. 8 | 9 | Steps for installing the plugin came from https://docs.confluent.io/home/connect/userguide.html#connect-installing-plugins 10 | 11 | To install the JDBC Connector: 12 | 1. Create a plugins directory (`mkdir -p kafka/plugins`) 13 | 1. Set the `plugin.path` property in the `config/connect-standalone.properties` file in your Kafka Connect installation (for instance, `plugin.path=/home/MYUSR/kafka/plugins`) 14 | 1. Extract the plugin archive in the plugins directory (for instance, `unzip confluentinc-kafka-connect-jdbc-10.2.0.zip` in the `kafka/plugins` directory) 15 | 16 | Steps for installing the JDBC drivers for use with the connector can be found at https://docs.confluent.io/current/connect/kafka-connect-jdbc/index.html#installing-jdbc-drivers 17 | 18 | **Important note: The jar files for the JDBC driver needs to be in the same directory as the jar file for the connector (for instance, `kafka/plugins/confluentinc-kafka-connect-jdbc-10.2.0/lib`). You can download the IBM Toolbox JDBC driver from [the JTOpen web site](http://jt400.sourceforge.net/) or copy it from `/QIBM/ProdData/OS400/jt400/lib/java8/jt400.jar`. Alternatively, you can use the IBM Db2 JDBC driver from DB2 Connect (you need both db2jcc4.jar and db2jcc_license_cisuz.jar).** 19 | 20 | A worker configuration for each JDBC connector needs to be created. These can be different for the Toolbox JDBC driver and the IBM DB2 JDBC driver. 21 | 22 | Here is an example using the Toolbox JDBC driver, limiting the connector to reading data from KC_JTOPEN.EMPLOYEE: 23 | 24 | file: `config/worker-jtopen.properties` 25 | 26 | contents: 27 | ``` 28 | name=jdbc_source_jtopen_01 29 | connector.class=io.confluent.connect.jdbc.JdbcSourceConnector 30 | connection.url=jdbc:as400://mysystem.mycompany.com 31 | connection.user=MYUSR 32 | connection.password= 33 | topic.prefix=jtopen-01- 34 | mode=bulk 35 | poll.interval.ms=3600000 36 | schema.pattern=KC_JTOPEN 37 | table.whitelist=EMPLOYEE 38 | ``` 39 | And here is an example using the IBM DB2 JDBC driver, limiting the connector to reading data from KC_DB2.EMPLOYEE: 40 | 41 | file: `config/worker-db2.properties` 42 | 43 | contents: 44 | ``` 45 | name=jdbc_source_db2_01 46 | connector.class=io.confluent.connect.jdbc.JdbcSourceConnector 47 | connection.url=jdbc:ibmdb://mysystem.mycompany.com:446/*LOCAL 48 | connection.user=MYUSR 49 | connection.password= 50 | topic.prefix=db2-01- 51 | mode=bulk 52 | poll.interval.ms=3600000 53 | schema.pattern=KC_DB2 54 | table.whitelist=EMPLOYEE 55 | ``` 56 | 57 | Assuming zookeeper and the Kafka server are already running, start connect using the worker configurations: 58 | ``` 59 | bin/connect-standalone.sh config/connect-standalone.properties config/worker-jtopen.properties config/worker-db2.properties 60 | ``` 61 | 62 | Assuming you are running Kafka on localhost, you can list the connectors using the following: 63 | ``` 64 | curl -s "http://localhost:8083/connectors" 65 | ``` 66 | 67 | You can list the status of a connector using something like the following: 68 | ``` 69 | curl -s "http://localhost:8083/connectors/jdbc_source_jtopen_01/status" | jq '.' 70 | curl -s "http://localhost:8083/connectors/jdbc_source_db2_01/status" | jq '.' 71 | ``` 72 | -------------------------------------------------------------------------------- /kafka/README.md: -------------------------------------------------------------------------------- 1 | # Kafka 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Streaming data to Kafka from IBM i 8 | There are several approaches to streaming data from Db2 transactions to Kafka, including but not limited to: 9 | 1. [Db2 triggers and Apache Camel](KAFKA_CAMEL_DTAQ.md): stream events in real-time 10 | 1. [Kafka Connect JDBC Source connector](KAFKA_CONNECT_JDBC.md): Simple, polling-based technique for importing Db2 data into Kafka 11 | 1. [Debesium Connector for IBM i](https://github.com/jhc-systems/debezium-connector-ibmi): leverages the [Debezium](https://debezium.io/) ecosystem for change data capture. 12 | 1. [Db2 WebQuery](https://techchannel.com/SMB/02/2023/IBM%E2%80%99s-DataMigrator-for-IBM-i) (external link): (**commercial offering**) Has a DataMigrator ETL extension that includes the ability to perform both bulk loads and incremental updates of data to Kafka. 13 | 1. [InfoSphere Data Replication and the CDC Replication Engine for Kafka](https://www.ibm.com/docs/en/idr/11.4.0?topic=replication-cdc-engine-kafka) (external link): (**commercial offering**) a CDC-based approach that may be a good options for current IBM CDC customers. Currently, this approach is unverified 14 | 1. [Native ILE Kafka client (unsupported)](https://github.com/AlexeiBaranov/librdkafka/blob/port-os400/packaging/os400/README.md) (external link): call Kafka functions directly from ILE programs. 15 | 1. The [Confluent Platform](https://docs.confluent.io/platform/current/platform.html) provides a number of tools for working with Kafka. To install, 16 | follow the steps for "using only Confluent Community components" 17 | [here](https://docs.confluent.io/platform/current/installation/installing_cp/zip-tar.html#prod-kafka-cli-install). The most notable components for IBM i 18 | integration are: 19 | - [ksqlDB](https://docs.confluent.io/platform/current/platform.html#ksqldb), which provides an SQL interface for doing Kafka streaming operations using one 20 | of the ksqlDB clients, such as the provided Java client. 21 | - [Kafka REST APIs](https://docs.confluent.io/platform/current/kafka-rest/index.html), which provides a REST interface for doing Kafka streaming operations. The REST interfaces can then be called from anywhere, including from Db2 triggers by way of [SQL HTTP functions in Db2](https://techchannel.com/Trends/09/2021/sql-http-part-2) (example below). 22 | 23 | ## Kafka via SQL 24 | 25 | You can use the new Db2 SDK to post messages to Kafka. See the docs [here](https://ibm.github.io/AI-SDK-Db2-IBMi/) for more information. 26 | 27 | ```sql 28 | values(dbsdk_v1.kafka_publish( TOPIC => 'fun_facts', 29 | KEY => 'baritone43', 30 | MSGDATA => 'The baritone is a very interesting musical instrument!')); 31 | ``` 32 | 33 | This can also be embedded as needed in a Db2 trigger. 34 | 35 | ## Deploying Kafka on IBM i 36 | 37 | These steps walk you through installing Kafka 3.0.1 (built with Scala 2.13) and deploying 38 | on an IBM i system using OpenJDK 39 | [Early Access Builds](https://ibmi-oss-docs.readthedocs.io/en/latest/java11/JAVA11_EARLY_ACCESS.html). 40 | 41 | This assumes you are using an SSH terminal and that you have 42 | [your PATH set up properly](https://ibmi-oss-docs.readthedocs.io/en/latest/troubleshooting/SETTING_PATH.html), 43 | for instance: 44 | ``` 45 | PATH=/QOpenSys/pkgs/bin:$PATH 46 | export PATH 47 | ``` 48 | and you are hopefully, but optionally, [using bash](https://ibmi-oss-docs.readthedocs.io/en/latest/troubleshooting/SETTING_BASH.html) 49 | 50 | Also, note that this deploys with the default "out of the box" settings for Zookeeper 51 | and Kafka. Please refer to the Zookeeper and Kafka documentation to learn about customizing 52 | these appropriately for a production deployment as needed. 53 | 54 | #### 1. Download requisite software 55 | ``` 56 | yum install wget ca-certificates-mozilla gzip tar-gnu openjdk-11 coreutils-gnu sed-gnu grep-gnu 57 | ``` 58 | 59 | #### 2. Change to your installation directory 60 | ``` 61 | cd /home/myusr/mydir 62 | ``` 63 | 64 | #### 3. Download kafka 65 | ``` 66 | wget https://dlcdn.apache.org/kafka/3.0.1/kafka_2.13-3.0.1.tgz 67 | ``` 68 | (you may need to update the version number on this and subsequent steps based on [the latest version](https://kafka.apache.org/downloads). 69 | 70 | #### 4. extract Kafka 71 | ``` 72 | tar xzvf kafka_2.13-3.0.1.tgz 73 | ``` 74 | 75 | #### 5. Set up environment to use OpenJDK 76 | ``` 77 | JAVA_HOME=/QOpenSys/pkgs/lib/jvm/openjdk-11 78 | export JAVA_HOME 79 | PATH=$JAVA_HOME/bin:$PATH 80 | export PATH 81 | ``` 82 | 83 | #### 6. Start a Zookeeper server 84 | ``` 85 | cd kafka_2.13-3.0.1/config 86 | ../bin/zookeeper-server-start.sh zookeeper.properties 87 | ``` 88 | 89 | #### 7. Open a new session and change to your installation directory from earlier 90 | ``` 91 | cd /home/myusr/mydir 92 | ``` 93 | 94 | #### 8. Set up environment to use OpenJDK and start a Kafka server 95 | ``` 96 | JAVA_HOME=/QOpenSys/pkgs/lib/jvm/openjdk-11 97 | export JAVA_HOME 98 | PATH=$JAVA_HOME/bin:$PATH 99 | export PATH 100 | cd kafka_2.13-3.0.1/config 101 | ../bin/kafka-server-start.sh server.properties 102 | ``` 103 | 104 | ## Starting a Kafka visualizer 105 | 106 | The Kafka visualizer used for the interactive workshop is an open source, Java-based visualizer that is accessed through 107 | a web browser. The [project page](https://github.com/manasb-uoe/kafka-visualizer) has more information. It can be installed 108 | with docker via 109 | ``` 110 | docker pull kbhargava/kafka-visuals 111 | ``` 112 | and run like this (substitute host names and port numbers as appropriate). 113 | ``` 114 | docker run -p 8080:8080 --rm kbhargava/kafka-visuals idevphp.idevcloud.com:2181 idevphp.idevcloud.com:9092 DEV 115 | ``` 116 | 117 | If you want to run this visualizer on IBM i, install via yum: 118 | ``` 119 | yum install ca-certificates-mozilla 120 | yum install https://github.com/ThePrez/kafka-visualizer/releases/download/v1.0.0/kafka-visualizer-1.0.0-0.ibmi7.3.ppc64.rpm 121 | ``` 122 | ... and run using the following command and navigate to `localhost:8080` on your browser: 123 | 124 | ``` 125 | /opt/kafka-visualizer/bin/kafka-visualizer 126 | ``` 127 | 128 | 129 | You can opt to use any kafka visualizer you'd like. Kafka even comes with a single-topic visualizer that can run in your SSH terminal, for instance 130 | 131 | ``` 132 | JAVA_HOME=/QOpenSys/pkgs/lib/jvm/openjdk-11 133 | export JAVA_HOME 134 | PATH=$JAVA_HOME/bin:$PATH 135 | export PATH 136 | cd kafka_2.13-3.0.1/config 137 | ../bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic mytopic 138 | ``` 139 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /mariadb/MIGRATION-10.6.md: -------------------------------------------------------------------------------- 1 | # Migrating from MariaDB 10.3.x MariaDB 10.6.x 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Notable Differences 8 | 9 | ### [Binary Name Changes](https://mariadb.com/kb/en/upgrading-from-mariadb-104-to-mariadb-105/#binary-name-changes) 10 | All binaries previously beginning with mysql now begin with mariadb, with symlinks for the corresponding mysql command. 11 | 12 | Usually that shouldn't cause any changed behavior, but when starting the MariaDB server via the mysqld_safe script symlink, the server process will now always be started as mariadbd, not mysqld. 13 | 14 | So anything looking for the mysqld name in the system process list, like e.g. monitoring solutions, now needs to check for mariadbd instead when the server / service is not started directly, but via mysqld_safe or as a system service. 15 | 16 | ### [Unix Socket Authentication](https://mariadb.com/kb/en/upgrading-from-mariadb-103-to-mariadb-104/#authentication-and-tls) 17 | 18 | Since 10.4 MariaDB, switched to use the [unix_socket authentication plugin](https://mariadb.com/kb/en/authentication-plugin-unix-socket/) is now default on Unix-like systems. On IBM i this is disabled due to limitations in PASE. 19 | 20 | ### [Reserved Word](https://mariadb.com/kb/en/upgrading-from-mariadb-10-5-to-mariadb-10-6/#reserved-word) 21 | New reserved word: OFFSET. This can no longer be used as an identifier without being quoted. 22 | 23 | ### [InnoDB COMPRESSED Row Format](https://mariadb.com/kb/en/upgrading-from-mariadb-10-5-to-mariadb-10-6/#innodb-compressed-row-format) 24 | From MariaDB 10.6.0 until MariaDB 10.6.5, tables that are of the COMPRESSED row format are read-only by default. This was intended to be the first step towards removing write support and deprecating the feature. 25 | 26 | This plan has been scrapped, and from MariaDB 10.6.6, COMPRESSED tables are no longer read-only by default. 27 | 28 | From MariaDB 10.6.0 to MariaDB 10.6.5, set the innodb_read_only_compressed variable to OFF to make the tables writable. 29 | 30 | ### [Character Sets](https://mariadb.com/kb/en/upgrading-from-mariadb-10-5-to-mariadb-10-6/#character-sets) 31 | From MariaDB 10.6, the utf8 character set (and related collations) is by default an alias for utf8mb3 rather than the other way around. It can be set to imply utf8mb4 by changing the value of the old_mode system variable. 32 | 33 | **NOTE**: 34 | For IBM builds the default character set and collations are set to utf8mb4 by default. 35 | 36 | ### [Disks Plugin](https://mariadb.com/kb/en/disks-plugin/) 37 | The disk plugin as is now enabled by default and seems to function well. 38 | 39 | ### For full list of changes take a look at MariaDB upgrading docs: 40 | - https://mariadb.com/kb/en/upgrading-from-mariadb-103-to-mariadb-104/#incompatible-changes-between-103-and-104 41 | - https://mariadb.com/kb/en/upgrading-from-mariadb-104-to-mariadb-105/#incompatible-changes-between-104-and-105 42 | - https://mariadb.com/kb/en/upgrading-from-mariadb-10-5-to-mariadb-10-6/#incompatible-changes-between-105-and-106 43 | 44 | Also checkout the [MariaDB 10.6 release notes](https://mariadb.com/kb/en/changes-improvements-in-mariadb-106/) for more info. 45 | 46 | 47 | ## Migration Steps 48 | 49 | MariaDB 10.6 conflicts with and is not co-installable with MariaDB 10.3. 50 | 51 | 1. Backup your existing data using [mysqldump](https://mariadb.com/kb/en/backup-and-restore-overview/#mysqldump) 52 | ```sh 53 | # you will be prompted to enter the password 54 | mysqldump --all-databases --routines --events --user root --password > db.bak 55 | ``` 56 | 57 | 2. Stop the MariaDB Server 58 | ```sh 59 | # you will be prompted to enter the password 60 | mysqladmin shutdown --user root --password 61 | ``` 62 | 63 | 3. Remove MariaDB 10.3.x packages 64 | 65 | ```sh 66 | yum remove mariadb-server mariadb 67 | ``` 68 | 69 | 4. Install MariaDB 10.6.x packages 70 | ```sh 71 | yum install mariadb-10.6-server mariadb-10.6 72 | ``` 73 | 74 | 5. Start MariaDB 10.6.x Server 75 | 76 | 77 | ```sh 78 | mariadbd-safe & 79 | # NOTE: If IPv6 is disabled you will need to explicitly set the bind address 80 | # For example: 81 | # mariadbd-safe --bind-address=0.0.0.0 & 82 | # Refer to the MariaDB docs for more info 83 | # https://mariadb.com/kb/en/configuring-mariadb-for-remote-client-access/ 84 | # https://mariadb.com/kb/en/server-system-variables/#bind_address 85 | ``` 86 | 87 | 6. Run `mariadb-upgrade` 88 | 89 | ```sh 90 | # you will be prompted to enter the password 91 | mariadb-upgrade --user root --password 92 | ``` 93 | -------------------------------------------------------------------------------- /mariadb/README.md: -------------------------------------------------------------------------------- 1 | # MariaDB 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | MariaDB is available part of the IBM i RPM ecosystem! 8 | 9 | Currently the following versions of MariaDB are available: 10 | - 10.3 11 | - 10.6 12 | 13 | MariaDB 10.3 is going out of support May 2023. 14 | 15 | See migration page for details about upgrading from 10.3 to 10.6. 16 | 17 | ## Contents 18 | 19 | ```{toctree} 20 | :maxdepth: 1 21 | Migrating from MariaDB 10.3.x to MariaDB 10.6.x 22 | ``` 23 | -------------------------------------------------------------------------------- /nginx/README.md: -------------------------------------------------------------------------------- 1 | # NGINX 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Summary 8 | 9 | Here you will find general information as it relates to Nginx on IBM i. This is 10 | meant to be a supplement to the [official Nginx documentation](https://docs.nginx.com) 11 | and the wealth of public information available online. Generally speaking, Nginx on IBM i 12 | is managed the same way as on other platforms. 13 | 14 | As outlined in [the Apache documentation](../apache/README.md), there are several advantages 15 | to using an HTTP server in front of your application. It is not good practice to serve up 16 | directly from a framework or application server in production. 17 | 18 | **Of note: Apache (IBM HTTP Server for i) uses Digital Certificate Manager (DCM) to configure 19 | TLS. Nginx uses standard OpenSSL technology** 20 | 21 | ## Install 22 | 23 | ```bash 24 | yum install nginx 25 | ``` 26 | 27 | ## Simple static HTML server example 28 | 29 | The following can be placed in file `/www/nginx/nginx.conf`. 30 | 31 | ```nginx 32 | pid /www/nginx/nginx.pid; 33 | events {} 34 | http { 35 | server { 36 | listen 8001; 37 | server_name localhost; 38 | location / { 39 | root /www/nginx/html; 40 | index index.html; 41 | } 42 | } 43 | } 44 | ``` 45 | 46 | ## Starting and Stopping 47 | 48 | To start Nginx you need use use the `/QOpenSys/pkgs/bin/nginx` binary and the 49 | `-c` option to declare where the config location. This is like submitting a job 50 | to batch in that it won't lock up your console. 51 | 52 | ```bash 53 | nginx -c /www/nginx/nginx.conf 54 | ``` 55 | 56 | To stop, run this command. 57 | 58 | ```bash 59 | nginx -c /www/nginx/nginx.conf -s stop 60 | ``` 61 | 62 | You can also use the `-p` option to set the base directory. This allows relative 63 | path names in the configuration (pid file, logs, etc) to be resolved relative to the 64 | base directory. For instance, you can `cd` to the directory where you have your 65 | configuration file and run the following commands to start/stop. 66 | ```bash 67 | nginx -p $(pwd) -c $(pwd)/nginx.conf 68 | ``` 69 | ```bash 70 | nginx -p $(pwd) -c $(pwd)/nginx.conf -s stop 71 | ``` 72 | 73 | 74 | ## HTTP Reverse Proxy (and load balancing) 75 | 76 | The below shows how to have Nginx act as a reverse proxy to a Node.js web server 77 | listening on port 49000. It also redirects port 80 traffic to the secure port 78 | 443 (https) which in turn necessitates SSL configuration. 79 | To load-balance across multiple web server, simply add more entries to the 80 | `upstream` block. Note, you may have better performance at scale using a streaming 81 | reverse proxy (see below). 82 | 83 | ```nginx 84 | pid /www/mydomain/nginx.pid; 85 | events {} 86 | http { 87 | server { 88 | listen 80; 89 | server_name mydomain.com; 90 | return 301 https://$server_name$request_uri; 91 | } 92 | upstream node_servers { 93 | server 127.0.0.1:49000; 94 | } 95 | server { 96 | listen 443 ssl; 97 | ssl on; 98 | ssl_certificate /www/mydomain/mydomain.com.cert; 99 | ssl_certificate_key /www/mydomain/mydomain.com.key; 100 | ssl_protocols TLSv1.2; 101 | ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256 102 | ssl_session_cache shared:SSL:50m; 103 | ssl_prefer_server_ciphers on; 104 | location / { 105 | proxy_pass http://node_servers; 106 | } 107 | } 108 | } 109 | ``` 110 | 111 | ### Microcaching 112 | 113 | Nginx is also great at caching content. Caching for small durations is sometimes called "microcaching." 114 | This can be particularly useful if your web page or API can tolerate slightly-stale data. For example, 115 | let's imagine you have an API that runs a database query. Let's say it gets 500 requests per second. 116 | If you can tolerate data that is 3 seconds "old," then you can enable caching with a 3-second lifespan. 117 | With such a change, you'd go from making 30000 database queries per minute, to only 20 database queries 118 | per minute! Obviously, this is an extreme case, but caching can significantly reduce database load and 119 | improve throughput and response times when used effectively. Note, however, caching has its own 120 | overhead, so it should not be used when a high number of cache misses and a low level of cache hits are 121 | expected. 122 | 123 | The below example illustrates a 5-second microcaching setup, load-balanced across two backend Python 124 | servers. 125 | 126 | ```nginx 127 | pid nginx.pid; 128 | events {} 129 | http { 130 | error_log logs/error.log warn; 131 | proxy_cache_path /tmp/cache keys_zone=cache:10m levels=1:2 inactive=600s max_size=100m; 132 | upstream python_servers { 133 | server 127.0.0.1:3341; 134 | server 127.0.0.1:3342; 135 | } 136 | server { 137 | proxy_cache cache; 138 | proxy_cache_lock on; 139 | proxy_cache_valid 200 5s; 140 | proxy_cache_methods GET HEAD POST; 141 | proxy_cache_use_stale updating error timeout http_500 http_502 http_503 http_504; 142 | proxy_buffering on; 143 | listen 9333 backlog=8096; 144 | location / { 145 | proxy_pass http://python_servers; 146 | } 147 | location /tablesorter { 148 | autoindex on; 149 | alias tablesorter/; 150 | } 151 | } 152 | } 153 | ``` 154 | 155 | ## Streaming Reverse Proxy (and load balancing) 156 | 157 | Nginx also supports stream-based proxying and load balancing. This can work for many protocols 158 | (not just http) and consumes less overhead than an HTTP reverse proxy. However, since it doesn't 159 | do any HTTP-specific operations, it doesn't support any http-specific concepts (like HTTP redirects, 160 | header filtering/rewriting, "sticky" sessions, etc). The below shows how to load-balance across 161 | three backend servers running on ports 9000, 9001, and 9002. Note the relative paths for the 162 | pid file and error logs, so this configuration should be started with the `-p` option as shown above. 163 | 164 | ```nginx 165 | pid nginx.pid; 166 | events {} 167 | stream { 168 | error_log logs/error.log warn; 169 | upstream node_servers { 170 | server 127.0.0.1:9000; 171 | server 127.0.0.1:9001; 172 | server 127.0.0.1:9002; 173 | } 174 | server { 175 | listen 80 backlog=8096; 176 | proxy_pass node_servers; 177 | } 178 | } 179 | ``` 180 | 181 | Of note, the ssl directives can still be used with a streaming reverse proxy. Also, http concepts 182 | can still be handled by the application. You can also combine the `stream` blocks and `http` blocks 183 | into a single configuration. In the below example, nginx will redirect http traffic on port 80 184 | to https on port 443. On port 443, nginx will handle the TLS encryption and load balance between 185 | three backend servers running on ports 9000, 9001, and 9002. 186 | 187 | ```nginx 188 | pid nginx.pid; 189 | events {} 190 | stream { 191 | error_log logs/error.log warn; 192 | upstream python_servers { 193 | server 127.0.0.1:9000; 194 | server 127.0.0.1:9001; 195 | server 127.0.0.1:9002; 196 | } 197 | server { 198 | ssl_certificate my-cert.pem; 199 | ssl_certificate_key my-key.pem; 200 | ssl_protocols TLSv1.2; 201 | ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256; 202 | ssl_session_cache shared:SSL:50m; 203 | ssl_prefer_server_ciphers on; 204 | listen 443 ssl backlog=8096; 205 | proxy_pass python_servers; 206 | } 207 | } 208 | http { 209 | server { 210 | listen 80; 211 | server_name myserver.com; 212 | return 301 https://$server_name$request_uri; 213 | } 214 | } 215 | ``` 216 | -------------------------------------------------------------------------------- /nodejs/KNOWN-ISSUES.md: -------------------------------------------------------------------------------- 1 | # Known Issues 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## [fs.watch](https://nodejs.org/api/fs.html#fswatchfilename-options-listener) 8 | 9 | On IBM i systems, this feature is not supported. 10 | 11 | This is also documented in the [caveats](https://nodejs.org/api/fs.html#caveats) 12 | section of the `fs.watch` documentation. 13 | 14 | When using various Node.js tools for watching a filesystem and hot-reloading on 15 | file changes, many use Chokidar which relies on fs.watch, which is not supported 16 | on IBM i. This results in error messages such as: 17 | 18 | ```text 19 | Watchpack Error (watrcher): Error: ENONSYS: function not implmemented, watch 20 | Error from chokidar src/api/modules): error enosys: function not implemented, watch 21 | ``` 22 | 23 | As a workaround, Chokidar supports polling, which can be enabled by setting the 24 | `CHOKIDAR_USEPOLLING` environment variable to 1. 25 | 26 | As of `chokidar >= 3.5.2`, the default is to use polling on IBM i and it should 27 | work out of the box. 28 | 29 | As of `nodemon >= 3.0.1`, the default is to use polling on IBM i and it should 30 | work out of the box. 31 | 32 | ## [os.uptime](https://nodejs.org/api/os.html#osuptime) 33 | 34 | On IBM i systems, this feature is not supported. 35 | Calling `os.uptime` returns a system error `ENOSYS`. 36 | -------------------------------------------------------------------------------- /nodejs/README.md: -------------------------------------------------------------------------------- 1 | # Node.js usage notes 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | Known Issues 6 | ``` 7 | 8 | All things assume you have [PATH set correctly](../troubleshooting/SETTING_PATH.md) 9 | 10 | ## Choosing which major version of Node.js to use 11 | There are two ways to install Node.js: 12 | 1. Through the [package manager](https://nodejs.org/en/download/package-manager/all#ibm-i) (recommended for production. Note that there are different packages for different major versions. A simple `yum upgrade` will not upgrade any existing versions to a new major version. 13 | 2. Using [nvm](#using-node-version-manager-nvm) 14 | 15 | Consult the [Node.js release schedule](https://github.com/nodejs/Release) for guidance on which version of Node.js to use. Generally speaking: 16 | - Only even-numbered major releases should be deployed to production. The odd-numbered releases are feature releases designed to allow early access to new features. Feature releases lack both stability and a long-term support (LTS) schedule 17 | - Choose a version that is in "Active LTS" status for production applications. "Current" status is sometimes acceptable as well, as long as the release will be entering LTS soon. 18 | - **NEVER** run an out-of-support release 19 | - Ensure you have a plan to upgrade before the version's "end of life" date. 20 | 21 | ## Setting the Node.js major version 22 | 23 | - To switch the default version of Node.js for all users, use the 24 | `/QOpenSys/pkgs/bin/alternatives` utility. For instance, for Node.js version 20 to be 25 | the default, run: 26 | 27 | ```bash 28 | $ /QOpenSys/pkgs/bin/alternatives --config node 29 | There are 3 choices for the alternative node (providing /QOpenSys/pkgs/bin/node). 30 | 31 | Selection Path Priority Status 32 | ------------------------------------------------------------ 33 | 0 /QOpenSys/pkgs/lib/nodejs20/bin/node 20 auto mode 34 | 1 /QOpenSys/pkgs/lib/nodejs16/bin/node 16 manual mode 35 | * 2 /QOpenSys/pkgs/lib/nodejs18/bin/node 18 manual mode 36 | 3 /QOpenSys/pkgs/lib/nodejs20/bin/node 20 manual mode 37 | 38 | Press to keep the current choice[*], or type selection number: 3 39 | update-alternatives: using /QOpenSys/pkgs/lib/nodejs20/bin/node to provide /QOpenSys/pkgs/bin/node (node) in manual mode 40 | $ node --version 41 | v20.8.1 42 | ``` 43 | - If you need to explicitly invoke a specific major version of Node.js, the 44 | executable is found at `/QOpenSys/pkgs/lib/nodejs/bin/node`, where 45 | `` is the major version. For instance, to run Node.js version 20, one 46 | could run `/QOpenSys/pkgs/lib/nodejs20/bin/node` 47 | - To switch the default version of Node.js for a specific user, place 48 | `/QOpenSys/pkgs/lib/nodejs/bin` at the beginning of the user's PATH 49 | environment variable, similar to what's documented [here](../troubleshooting/SETTING_PATH.md). 50 | For instance, that user could run the following from the shell to set their 51 | default to version 20: 52 | 53 | ```bash 54 | echo 'PATH=/QOpenSys/pkgs/lib/nodejs20/bin:/QOpenSys/pkgs/bin:$PATH' >> $HOME/.profile 55 | echo 'export PATH' >> $HOME/.profile 56 | ``` 57 | 58 | (if using `bash` as the shell, the user may need to run `hash -r`) 59 | 60 | ## Globally-installed modules 61 | 62 | - To use `node-gyp` (or other globally-installed modules) from the command line, 63 | follow the same instructions in the previous section to add the version-specific 64 | directory to your `PATH` 65 | ## Modules for accessing Db2, RPG, CL etc 66 | 67 | - Be sure to use the `itoolkit` package from npm (`npm install itoolkit`) for accessing RPG, CL, etc. 68 | - For database access to the local system (running on IBM i), install one of the following packages from npm: 69 | - [`odbc`](https://www.npmjs.com/package/odbc) (see [the ODBC doc](../odbc/README.md) for further guidance on ODBC) 70 | - [`idb-connector`](https://www.npmjs.com/package/idb-connector) 71 | - [`idb-pconnector`](https://www.npmjs.com/package/idb-pconnector) 72 | - For remote database access (connecting from another system), install one of the following packages from npm: 73 | - [`odbc`](https://www.npmjs.com/package/odbc) (see [the ODBC doc](../odbc/README.md) for further guidance on ODBC) 74 | - [`ibm_db`](https://www.npmjs.com/package/ibm_db) (Note that this requires a Db2 Connect license) 75 | 76 | ## Coming from 5733-OPS? 77 | - Any globally-installed modules must be reinstalled. Note, however, that global 78 | installations of node modules are generally considered bad practice (with a few 79 | exceptions, like `node-gyp`). 80 | 81 | 82 | ## Using Node Version Manager (nvm) 83 | 84 | ### Step 1: Install developer tools 85 | 86 | From an SSH terminal, run: 87 | 88 | ```bash 89 | yum group install "Development Tools" 90 | yum install gcc10\* 91 | ``` 92 | 93 | ### Step 2: Install NVM 94 | 95 | First, install necessary prerequisites using [yum](../yum/README.md) to verify that you 96 | have curl and/or wget installed. Make sure you 97 | [set your PATH](../troubleshooting/SETTING_PATH.md) to utilize the new open 98 | source technology. 99 | 100 | Then, simply follow the installation steps on the 101 | [nvm project page](https://github.com/creationix/nvm/) 102 | 103 | ### Step 3: Configure your $HOME/.nvmrc file 104 | 105 | Create a file at `$HOME/.nvmrc`, with the following contents 106 | 107 | ```bash 108 | --dest-cpu=ppc64 109 | --without-snapshot 110 | --shared-openssl 111 | --without-perfctr 112 | ``` 113 | 114 | ### Step 4: Set necessary environment variables 115 | 116 | Set the following environment variables: 117 | 118 | ```bash 119 | OBJECT_MODE=64 120 | CC=gcc-10 121 | CXX=g++-10 122 | PYTHON_PLATFORM_COMPAT_IBMI=Y 123 | ``` 124 | 125 | Preferrably, set these in your `$HOME/.profile` and/or `$HOME/.bash_profile` 126 | (depending on your shell settings), by adding the following lines: 127 | 128 | ```bash 129 | OBJECT_MODE=64 130 | export OBJECT_MODE 131 | CC=gcc 132 | export CC 133 | CXX=g++ 134 | export CXX 135 | ``` 136 | 137 | ### Step 5: Run nvm 138 | 139 | NVM, like many open source commands, are best run from an SSH terminal. See the 140 | [nvm project page](https://github.com/creationix/nvm/) for example usages of the 141 | command. Some examples include: 142 | 143 | * `nvm install stable` : install the latest stable version 144 | * `nvm install --lts` : install the latest LTS release 145 | * `nvm use --lts` : use the latest LTS release 146 | -------------------------------------------------------------------------------- /odbc/README.md: -------------------------------------------------------------------------------- 1 | # ODBC 2 | 3 | Open Database Connectivity (ODBC) is a standardized API for connecting to 4 | databases that is cross-platform and cross-DBMS (Database Management System). 5 | By installing an general ODBC driver manager and a driver for your specific 6 | DBMS, the code that interacts with the ODBC API can be generalized. This makes 7 | ODBC a very powerful tool for both development and for production, as the 8 | application can be deployed on any system and talk to any DBMS as long as it has 9 | the correct drivers installed. 10 | 11 | ## Contents 12 | 13 | ```{toctree} 14 | :maxdepth: 1 15 | 16 | Why ODBC? 17 | Installing and configuring ODBC 18 | Using ODBC 19 | Examples 20 | ``` 21 | -------------------------------------------------------------------------------- /odbc/examples.md: -------------------------------------------------------------------------------- 1 | # Node.js Example 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | This quick example will demonstrate development on a non-IBM i machine against 8 | Db2 on i, and then how you would transfer that same code to run on IBM i when 9 | you are ready to run in production. 10 | 11 | For this example, we will be using Node.js and the `odbc` package available on 12 | NPM. Node.js is simply used as an example technology, and this same thing could 13 | be done with PHP, Python, R, or any other package that has the ability to 14 | connect to the ODBC driver manager. 15 | 16 | ## Setting Up Your Development Environment 17 | 18 | ### DSNs 19 | 20 | The following instructions assume you have set up your ODBC environment [as 21 | outlined in the sections above](#installation). On your development machine, 22 | define a private DSN similar to the following, adding in your system and user credentials: 23 | 24 | ```ini 25 | [MYDSN] 26 | Description = The IBM i System 27 | Driver = IBM i Access ODBC Driver 28 | System = PUT.YOUR.SYSTEM.HERE 29 | UserID = USERNAME 30 | Password = PASSWORD 31 | ``` 32 | 33 | ### Node.js 34 | 35 | To run through this example, you will need to have Node.js installed. You can 36 | find the downloads at the [official Node.js website](https://nodejs.org/en/download/) 37 | or through your system's package manager. 38 | 39 | When you have Node.js installed, navigate to a new folder to contain your 40 | project and run: 41 | 42 | ```bash 43 | npm init -y 44 | ``` 45 | 46 | This will create a file for you called `package.json`, which tracks software you 47 | download from npm (among other things). 48 | 49 | Next, install the `odbc` package, which allows Node.js to talk to your driver manager. 50 | 51 | ```bash 52 | npm install odbc 53 | ``` 54 | 55 | You now have everything you need to connect to Db2 for i from your development machine! 56 | 57 | ## Development 58 | 59 | Using the `odbc` package, you can use a connection string that only references 60 | the DSN you defined above. Once you have the connection created, all of your 61 | queries will be run against the IBM i system defined in the DSN. 62 | 63 | **`app.js`** 64 | 65 | ```javascript 66 | const odbc = require('odbc'); 67 | 68 | odbc.connect('DSN=MYDSN', (error, connection) => { 69 | if (error) { throw error; } 70 | // now have an open connection to IBM i from any Linux or Windows machine 71 | connection.query('SELECT * FROM QIWS.QCUSTCDT', (error, result) => { 72 | if (error) { throw error; } 73 | console.log(result); 74 | }) 75 | }); 76 | ``` 77 | 78 | ## Transfer to IBM i 79 | 80 | When you are ready to transfer your program to IBM i, you just need to make sure 81 | you have everything set up on that system. 82 | 83 | ### DSNs on IBM i 84 | 85 | Like on your development machine, you will have to install your driver manager 86 | and driver. Steps to do that can be found in [installation on IBM i](#installation-on-ibm-i) 87 | section. That section will also cover instructions for downloading the Db2 for i 88 | driver and how to configure your DSNs, though this example will use the default 89 | `*LOCAL` DSN. 90 | 91 | ### Node.js on IBM i 92 | 93 | Because we want to transfer our Node.js application to our IBM i system, we will 94 | have to have Node.js installed: 95 | 96 | ```bash 97 | yum install nodejs10 98 | ``` 99 | 100 | You will then have Node.js v10 on your system. You simply need to move your code 101 | over to your IBM i system. Because we want to connect to the local database, we 102 | change our DSN to be `*LOCAL` instead of `MYDSN`: 103 | 104 | **`app.js`** 105 | 106 | ```javascript 107 | const odbc = require('odbc'); 108 | 109 | odbc.connect('DSN=*LOCAL', (error, connection) => { 110 | if (error) { throw error; } 111 | // now have an open connection to IBM i from any Linux or Windows machine 112 | connection.query('SELECT * FROM QIWS.QCUSTCDT', (error, result) => { 113 | if (error) { throw error; } 114 | console.log(result); 115 | }) 116 | }); 117 | ``` 118 | -------------------------------------------------------------------------------- /odbc/installation.md: -------------------------------------------------------------------------------- 1 | # IBM i Access ODBC Installation 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | The instructions for installing and ODBC driver and manager and the IBM i ODBC 8 | driver for Db2 on i will depend on what operating system you are running. Select 9 | your operating system below to see setup instructions for getting ODBC on your 10 | system and connected to IBM i. 11 | 12 | * [IBM i](#ibm-i) 13 | * [Linux](#linux) 14 | * [Windows](#windows) 15 | * [macOS](#macOS) 16 | 17 | ## IBM i 18 | 19 | The ODBC driver for IBM i is provided in the `ibm-iaccess` package, so it can be 20 | easily installed with `yum`. For instance: 21 | ```bash 22 | yum install ibm-iaccess 23 | ``` 24 | 25 | Installing this RPM will do the following: 26 | - Install the IBM i Access ODBC driver 27 | - Install the `unixODBC` driver manager 28 | - Register the driver with the driver manager by putting the appropriate information 29 | in the `odbcinst.ini` file (see [using](./using.md)). 30 | - Create a datasource name (DSN) for your local system called `*LOCAL`. This is 31 | discussed further in the "[using](./using.md)" doc. 32 | 33 | ## Linux 34 | 35 | IBM now has RPM and DEB repositories for Linux available directly from IBM for the 36 | IBM i Access Client Solutions application package, which includes the IBM i 37 | Access ODBC driver. 38 | 39 | On Linux, we will be using unixODBC as our driver manager. Fortunately, unixODBC 40 | is automatically pulled in when you install the IBM i Access ODBC Driver for 41 | Linux, so there isn't any set up that you have to do for this stage. If you want 42 | to develop applications using ODBC packages like pyODBC for Python or odbc for 43 | Node.js, you will have to manually use yum to install `unixODBC-devel` as well. 44 | 45 | ### Installing the Repository 46 | 47 | The repositories are located under 48 | . 49 | 50 | #### Red Hat-based Distribution Setup 51 | 52 | ```shell 53 | curl https://public.dhe.ibm.com/software/ibmi/products/odbc/rpms/ibmi-acs.repo | sudo tee /etc/yum.repos.d/ibmi-acs.repo 54 | ``` 55 | 56 | #### SUSE-based Distribution Setup 57 | 58 | ```shell 59 | curl https://public.dhe.ibm.com/software/ibmi/products/odbc/rpms/ibmi-acs.repo | sudo tee /etc/zypp/repos.d/ibmi-acs.repo 60 | ``` 61 | 62 | #### Debian-based and Ubuntu-based Distribution Setup 63 | 64 | ```shell 65 | curl https://public.dhe.ibm.com/software/ibmi/products/odbc/debs/dists/1.1.0/ibmi-acs-1.1.0.list | sudo tee /etc/apt/sources.list.d/ibmi-acs-1.1.0.list 66 | ``` 67 | 68 | ### Installing the ODBC driver 69 | 70 | #### Red Hat-based Distribution Installation 71 | 72 | ```shell 73 | sudo dnf install --refresh ibm-iaccess 74 | ``` 75 | 76 | #### SUSE-based Distribution Installation 77 | 78 | ```shell 79 | sudo zypper refresh 80 | sudo zypper install ibm-iaccess 81 | ``` 82 | 83 | #### Debian-based and Ubuntu-based Distribution Installation 84 | 85 | ```shell 86 | sudo apt update 87 | sudo apt install ibm-iaccess 88 | ``` 89 | ## Windows 90 | 91 | ### Driver Manager for Windows 92 | 93 | Windows comes preinstalled with an ODBC driver manager. To access it, search for 94 | `Administrative Tools` on your system (either through the search bar, or 95 | `Control Panel > System and Security > AdministrativeTools`), and then from 96 | there select ODBC Data Sources (either 32-bit or 64-bit). 97 | 98 | From this application, you can set up your drivers. 99 | 100 | ### Driver for Windows 101 | 102 | You will have to install the ODBC driver that allows Windows ODBC driver manager 103 | to talk to Db2 on i. To get the driver, visit 104 | [the IBM i Access Client Solutions page](https://www-01.ibm.com/support/docview.wss?uid=isg3T1026805) 105 | and select **Downloads for IBM i Access Client Solutions**. After logging in and 106 | redirected to the IBM I Access Client Solutions download page, scroll down and 107 | download the **ACS Windows App Pkg English (64bit)**. 108 | 109 | When the package has been downloaded and has been installed on your system, it 110 | should be available to see on your ODBC Data Source Administrator application. 111 | 112 | ## macOS 113 | 114 | ### Driver Manager for macOS 115 | 116 | On macOS, you will need unixODBC as your ODBC driver manager. Many macOS ODBC 117 | programs use another driver manager called **iodbc**, but *the IBM i ODBC driver 118 | will not work with iodbc*. unixODBC is available from 119 | [Homebrew](https://brew.sh), and can be installed running the following 120 | command: 121 | 122 | ```shell 123 | brew install unixodbc 124 | ``` 125 | 126 | ### Driver for macOS 127 | 128 | IBM now has a repository for the macOS driver as well. This repository is set 129 | up as a [Tap](https://docs.brew.sh/Tap). 130 | 131 | 132 | ### Installing the Repository 133 | 134 | The repositories are located under 135 | . 136 | 137 | 138 | ```shell 139 | brew tap ibm/iaccess https://public.dhe.ibm.com/software/ibmi/products/odbc/macos/tap/ 140 | ``` 141 | 142 | ### Installing the ODBC driver 143 | 144 | ```shell 145 | brew install ibm-iaccess 146 | ``` 147 | -------------------------------------------------------------------------------- /odbc/using.md: -------------------------------------------------------------------------------- 1 | # Using ODBC 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | Now that you have the IBM i Access ODBC Driver installed on your system, you are 8 | ready to connect to Db2 on i. 9 | 10 | ## Connection Strings 11 | 12 | ODBC uses a connection string with keywords to create a database connection. 13 | Keywords are case insensitive, and values passed are separated from the keyword 14 | by an equals sign ("`=`") and end with a semi-colon ("`;`"). As long as you are 15 | using an ODBC database connector, you should be able to pass an identical 16 | connection string in language or technology and be confident that it will 17 | correctly connect to Db2 on i. A common connection string may look something like: 18 | 19 | ```ODBC connection string 20 | DRIVER=IBM i Access ODBC Driver;SYSTEM=my.ibmi.system;UID=foo;PWD=bar; 21 | ``` 22 | 23 | In the above example, we define the following connection options: 24 | 25 | * DRIVER: The ODBC driver for Db2 for i that we are using to connect to the 26 | database (and that we installed above) 27 | * SYSTEM: The location of your IBM i system, which can be its network name, IP 28 | address, or similar 29 | * UID: The User ID that you want to use on the IBM i system that you are 30 | connecting to 31 | * PWD: The password of the User ID passed above. 32 | 33 | These are only some of the over 70 connection options you can use when 34 | connecting to Db2 on i using the IBM i Access ODBC Driver. A complete list of 35 | IBM i Access ODBC Driver connection options can be found at the 36 | [IBM Knowledge Center: Connection string keywords webpage](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzaik/connectkeywords.htm). 37 | If passing connections options through the connection string, be sure to use the 38 | keyword labeled with **Connection String**. 39 | 40 | ## DSNs 41 | 42 | As you add more and more options to your connection string, your connection 43 | string can become quite cumbersome. Luckily, ODBC offers another way of defining 44 | connection options called a DSN (datasource name). Where you define your DSN 45 | will depend on whether you are using Windows ODBC driver manager or unixODBC on 46 | Linux or IBM i. 47 | 48 | ### Configuration with UnixODBC (IBM i, Linux, macOS) 49 | 50 | IBM i, Linux distributions, and macOS use unixODBC and have nearly identical 51 | methods of setting up your drivers and your DSNs. 52 | 53 | **`odbc.ini` and `.odbc.ini`** 54 | 55 | When using unixODBC, DSNs are defined in `odbc.ini` and `.odbc.ini` (note the 56 | `.` preceding the latter). These two files have the same structure, but have one 57 | important difference: 58 | 59 | * `odbc.ini` defines DSNs that are available to **all users on the system**. 60 | If there are DSNs that should be available to everyone, they can be defined and 61 | shared here. Likely, this file is located in the default location, which depends 62 | on whether you are on IBM i or Linux: 63 | 64 | * IBM i: `/QOpenSys/etc/odbc.ini` 65 | * Linux: `/etc/unixODBC/odbc.ini` 66 | 67 | If you want to make sure, the file can be found by running: 68 | 69 | ```bash 70 | odbcinst -j 71 | ``` 72 | 73 | * `.odbc.ini` is found in your home directory (`~/`) and defines DSNs that are 74 | available **only to you**. If you are going to define DSNs with your personal 75 | username and password, this is the place to do it. 76 | 77 | In both `odbc.ini` and `.odbc.ini`, you name your DSN with `[]` brackets, then 78 | specify keywords and values below it. An example of a DSN stored in 79 | `~/.odbc.ini` used to connect to an IBM i system with private credentials might 80 | look like: 81 | 82 | ```ini 83 | [MYDSN] 84 | Description = My IBM i System 85 | Driver = IBM i Access ODBC Driver 86 | System = my.ibmi.system 87 | UserID = foo 88 | Password = bar 89 | Naming = 0 90 | DefaultLibraries = MYLIB 91 | TrueAutoCommit = 1 92 | ``` 93 | 94 | (**Note:** The name of the driver specified in the `Driver` keyword must match 95 | the name of a driver defined in `odbcinst.ini`. The location of this file can 96 | also be found by running `odbcinst -j` in PASE. When you install the IBM i 97 | Access ODBC Driver on your system, it automatically creates a driver entry of 98 | `IBM i Access ODBC Driver` in `odbcinst.ini`, which you should use for all 99 | IBM i connections). 100 | 101 | When installing the IBM i Access ODBC Driver on IBM i, the driver will 102 | automatically create a DSN called `[*LOCAL]` in your `odbc.ini`: 103 | 104 | ```ini 105 | ### IBM provided DSN - do not remove this line ### 106 | [*LOCAL] 107 | Description = Default IBM i local database 108 | Driver = IBM i Access ODBC Driver 109 | System = localhost 110 | UserID = *CURRENT 111 | ### Start of DSN customization 112 | ### End of DSN customization 113 | ### IBM provided DSN - do not remove this line ### 114 | ``` 115 | 116 | When using this DSN, the user credentials used will be `*CURRENT`, which is the 117 | user who is running the process that is trying to connect to the ODBC driver. 118 | Use of this `*CURRENT` behavior is dependent on some server PTFs: 119 | 120 | * 7.2: SI68113 121 | * 7.3: SI69058 122 | * 7.4: (none, comes with the operating system) 123 | 124 | Like connection string keywords, DSN keywords can be found at the 125 | [IBM Knowledge Center: Connection string keywords webpage](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzaik/connectkeywords.htm). 126 | When passing connection options through a DSN, be sure to use the keyword 127 | labeled with **ODBC.INI**. 128 | 129 | ### Configuration on Windows 130 | 131 | When you have the driver installed on your system, you can now configure your 132 | datasource names (DSNs) that allow you to wrap all of your connection settings 133 | in one place that can be used by any ODBC application. 134 | 135 | In ODBC Data Source Administrator, you can define either User DSNs or System 136 | DSNs. A User DSN will be available only to your Windows user, while a System DSN 137 | will be available to everyone. Furthermore, System DSNs must be defined 138 | per-architecture, while User DSNs are architecture agnostic. 139 | 140 | To create a DSN, select either User DSN or System DSN and then select `Add` on 141 | the right-hand menu. It will prompt you to select a driver, and you will select 142 | `IBM i Access ODBC Driver`. Use the GUI to add configuration options, such as 143 | your username and passwords, threading, default library, and so on. 144 | 145 | ### Using Your DSN 146 | 147 | Once you have DSNs defined with the connection options you want, you can simply 148 | pass a connection string to your ODBC connections that references the DSN: 149 | 150 | ```ODBC connection string 151 | DSN=MYDSN 152 | ``` 153 | 154 | This will look through your DSNs for a match, and pull in all connection options 155 | defined therein. This helps keep your connection string much more manageable, 156 | and also keeps your connections string more secure, as you don't have to 157 | explicitly pass your password in plain text. 158 | 159 | Additional options can be added to your connection string even if you use a DSN. 160 | In this way, you can extend your DSNs with options that make sense for a given 161 | use. To add more options, simply list them as you would any normal connection string: 162 | 163 | ```ODBC connection string 164 | DSN=MYDSN;DBQ=MYLIB,OTHERLIB;CCSID=1208; 165 | ``` 166 | 167 | Note that connection keywords specified on the connection string will override a 168 | DSN keyword that has the same functionality (e.g. a `CMT` value on the 169 | connection string will override any `CommitMode` defined for a DSN used in that 170 | connection string). 171 | -------------------------------------------------------------------------------- /odbc/why-odbc.md: -------------------------------------------------------------------------------- 1 | # Why ODBC 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | For the open-source software team, ODBC is the preferred method of connecting to 8 | Db2 on i. There are many resons for this, including: 9 | 10 | * Because ODBC is a technology that is used for more than just IBM i, there are 11 | many applications and technologies that are already enabled to use ODBC. Nearly 12 | all open-source programming languages (and many non-open-source languages) have 13 | some way to connect to databases through an ODBC interface, facilitating 14 | interaction with any database that has an ODBC driver (including IBM i). 15 | 16 | * Similarly, because ODBC connectors have already been developed for so many 17 | languages and frameworks, the IBM i Open-Source Software Team doesn’t have to 18 | spend time creating specific Db2 for i connectors for every new technology we 19 | deliver on the platform. This means that we can spend more time delivering new 20 | software for you and pushing what is possible on IBM i. In the future, most of 21 | the packages we develop will require that you use ODBC connections. 22 | 23 | * As already mentioned, ODBC is useful if you want to connect to Db2 on i from 24 | off-system. Unlike CLI-based connectors, which can only be built on IBM i, ODBC 25 | connections can be created from Windows and Linux machines as well. This means 26 | that you can develop your applications on one system and then move them to IBM i 27 | when you are ready to deploy them. It also means that you can have the same 28 | application running on multiple different platforms that can all communicate 29 | with Db2 on i in the same way. 30 | 31 | * Finally, there are many more connection options available for ODBC than on 32 | CLI. When you create an ODBC connection through a DSN or a connection string, 33 | there are approximately 70 different connection options that can be set. This 34 | includes everything from specifying the system, your username, or your password, 35 | to defining default libraries and schemas or whether or not stored procedures 36 | can be called. A full list of options can be found on the 37 | [“Connection string keywords” page of the 7.4 documentation](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzaik/connectkeywords.htm). 38 | -------------------------------------------------------------------------------- /porting/GOTCHAS.md: -------------------------------------------------------------------------------- 1 | # Gotchas When Building Software in PASE 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## malloc behaves differently from many other platforms 8 | 9 | [Zero byte allocations](https://whatilearned2day.wordpress.com/2006/07/13/zero-sized-allocation-using-malloc-on-aix/) 10 | on AIX can be strange. If software depends on this behaviour, you can build with 11 | `-D_LINUX_SOURCE_COMPAT` to enable a built-into-libc wrapper that has the glibc behaviour. 12 | 13 | ## C++ issues 14 | 15 | Make sure that you have `libstdcplusplus-devel` in addition to g++ installed. 16 | 17 | If you run into issues with the threading parts of the C++ standard library, 18 | such as `std::mutex`, ensure that `-pthread` is passed to g++. This will flip 19 | some defines and such so that threading is exposed. Linking pthread (`-pthread` 20 | if you use GCC as the linker, otherwise `-lpthread`) in also helps with crashes 21 | in C++ standard library locale code. 22 | 23 | ## AF_LOCAL not declared 24 | 25 | ```text 26 | error: 'AF_LOCAL' was not declared in this scope 27 | c = socket(AF_LOCAL, SOCK_STREAM, 0); 28 | ^~~~~~~~ 29 | ``` 30 | 31 | On some platforms, `AF_LOCAL` is provided as a synonym of `AF_UNIX`, but not on 32 | AIX/PASE. Either alter the code to use `AF_UNIX` directly or add your own synonym: 33 | 34 | ```C 35 | #ifndef AF_LOCAL 36 | #define AF_LOCAL AF_UNIX 37 | #endif 38 | 39 | // ... 40 | c = socket(AF_LOCAL, SOCK_STREAM, 0); 41 | ``` 42 | 43 | ## TOC overflow 44 | 45 | ```text 46 | ld: 0711-781 ERROR: TOC overflow. TOC size: 85080 Maximum size: 65536 47 | collect2: error: ld returned 12 exit status 48 | ``` 49 | 50 | Understanding the TOC (table of contents) could take up its own entire article. 51 | Indeed there's a good one [here](https://www.ibm.com/developerworks/rational/library/overview-toc-aix/index.html). 52 | The usual way to fix is by passing `-bbigtoc` option to the linker (`ld`). 53 | Using GCC, you need to prefix linker flags with `-Wl,` and these flags are 54 | specified in `$LDFLAGS`: 55 | 56 | ```bash 57 | export LDFLAGS='-Wl,-bbigtoc' 58 | ./configure ... 59 | make ... 60 | ``` 61 | 62 | While `-bbigtoc` should always do the job, it's not the most efficient. GCC also 63 | has additional ways to reduce TOC pressure that may be better performing, but 64 | you'll need to understand the code you're trying to compile and what each option 65 | does to apply them. Look for more info on the following compiler options [here](https://gcc.gnu.org/onlinedocs/gcc/RS_002f6000-and-PowerPC-Options.html#RS_002f6000-and-PowerPC-Options): 66 | 67 | - `-mno-fp-in-toc` 68 | - `-mno-sum-in-toc` 69 | - `-mminimal-toc` 70 | - `-mcmodel=medium` 71 | - `-mcmodel=large` 72 | 73 | ## `readdir_r` return values 74 | 75 | On AIX and PASE, `readdir_r` returns 9 and sets the result to NULL for both end 76 | of directory and error; on error, it sets `errno`. This is unlike other Unix 77 | systens and very easy to use incorrectly even when adapting to its quirks, so 78 | you can try: 79 | 80 | - Set `errno` to 0 before calling. This means you can disambiguate between the cases. 81 | - Build with `-D_LINUX_SOURCE_COMPAT`. This will point `readdir_r` to an 82 | alternative version with glibc-like semantics. 83 | 84 | ## `uname` return values 85 | 86 | Mostly a cosmetic issue, but applications expecting a full version in the 87 | release field of utsname will be disappointed. AIX and PASE put the major 88 | version (you know, the "V" in "V7R3") in version, and the minor version (the 89 | "R") in release. 90 | 91 | ## Thread safety 92 | 93 | AIX and PASE are **not** thread safe by default. You should pass 94 | `-D_THREAD_SAFE`, which enables important things like a thread-safe `errno`. 95 | 96 | ## VFS woes 97 | 98 | `mntctl`, `statvfs`, and ILE `statvfs` can never agree on a consistent value for 99 | magic names and numbers, unlike AIX. Try to avoid converting between their values. 100 | 101 | ## SIOCGIFCONF 102 | 103 | On PASE, `SIOCGIFCONF` doesn't show the true line description name, nor does it 104 | return an `AF_LINK` entry; the device will have a fake name based on its IPv4 address. 105 | This makes getting the interface index and MAC address nearly impossible; you 106 | can't even use `if_nameindex` because that returns the true line description name. 107 | As an alternative, you can use `Qp2getifaddrs`, which works like most Unix-like 108 | systems' `getifaddrs`. 109 | -------------------------------------------------------------------------------- /porting/PASE-TO-AIX-LEVEL.md: -------------------------------------------------------------------------------- 1 | # Map PASE/IBM i Version to AIX Version 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ```{eval-rst} 8 | +---------------+-------------+ 9 | | IBM i Version | AIX Version | 10 | +===============+=============+ 11 | | 7.6 | 7.3 TL1 | 12 | +---------------+-------------+ 13 | | 7.5 | 7.2 TL5 | 14 | +---------------+-------------+ 15 | | 7.4 | 7.2 TL2 | 16 | +---------------+-------------+ 17 | | 7.3 | 7.1 TL4 | 18 | +---------------+-------------+ 19 | | 7.2 | 7.1 TL1 | 20 | +---------------+-------------+ 21 | | 7.1 | 6.1 TL2 | 22 | +---------------+-------------+ 23 | | 6.1 | 5.3 TL6 | 24 | +---------------+-------------+ 25 | | 5.4 | 5.3 ML3 | 26 | +---------------+-------------+ 27 | ``` 28 | -------------------------------------------------------------------------------- /porting/README.md: -------------------------------------------------------------------------------- 1 | # Porting Software to PASE 2 | 3 | ## Contents 4 | 5 | ```{toctree} 6 | :maxdepth: 1 7 | 8 | Porting Gotchas 9 | PASE to AIX Level Mapping 10 | ``` 11 | -------------------------------------------------------------------------------- /postgresql.md: -------------------------------------------------------------------------------- 1 | # PostgreSQL Installation and Basic Configuration on IBM i 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | The purpose of this document is to summarize PostgreSQL installation and basic 8 | configuration on IBM i. The following topics are outlined below: initial setup, 9 | enabling remote connections, server startup, and connecting with a client. 10 | 11 | ## Initital Setup 12 | 13 | Install the `postgres12-server` and `postgresql-contrib` rpm packages using the 14 | [IBM i ACS Open Source Package Management](https://www.ibm.com/support/pages/node/706903) 15 | wizard or an SSH shell session with: 16 | 17 | ```bash 18 | yum install postgresql12-server postgresql12-contrib 19 | ``` 20 | 21 | According to the [PostgreSQL docs](https://www.postgresql.org/docs/12/postgres-user.html), 22 | "It is advisable to run PostgreSQL under a separate user account. This user 23 | account should only own the data that is managed by the server, and should not 24 | be shared with other daemons. The user name postgres is often used but you can 25 | use another name if you like." 26 | 27 | From a 5250 session create a ***POSTGRES*** user profile with: 28 | 29 | ```text 30 | CRTUSRPRF USRPRF(POSTGRES) PASSWORD(...) 31 | ``` 32 | 33 | ***NOTE:*** Creating a user profile requires `*ALLOBJ` authority. 34 | 35 | Next create the `postgres` home directory and change ownership to the 36 | ***POSTGRES*** user. From SSH or QSH session run: 37 | 38 | ```sh 39 | mkdir /home/postgres 40 | chown postgres /home/postgres 41 | ``` 42 | 43 | ***NOTE:*** Creating a directory under `/` requires `*ALLOBJ` authority. 44 | 45 | Log in to your IBM i via SSH as the **POSTGRES** user. 46 | 47 | If not started, start the bash shell by typing ***bash*** unless bash is already 48 | your default shell. 49 | 50 | Run the following commands to initialize PostgreSQL database in the 51 | `/home/postgres` IFS directory location 52 | 53 | ```bash 54 | 55 | export PGDATA=/home/postgres 56 | 57 | initdb -E UTF-8 -D /home/postgres -W -A scram-sha-256 58 | ``` 59 | 60 | You will be prompted to `Enter new superuser password` for the **POSTGRES** 61 | user. 62 | 63 | ***NOTE:*** This password is for the database and distinct from the **POSTGRES** 64 | user profile. 65 | 66 | After running `initdb` you should see the following message: 67 | 68 | ```text 69 | Success. You can now start the database server using: 70 | pg_ctl -D /home/postgres -l logfile start 71 | ``` 72 | 73 | ## Server Startup 74 | 75 | Run the following command to start PostgreSQL database server. 76 | 77 | ```bash 78 | pg_ctl -D /home/postgres -l logfile start 79 | ``` 80 | 81 | You should see the following messages: 82 | 83 | ```text 84 | waiting for server to start.... done 85 | server started 86 | ``` 87 | 88 | The following command can be used to stop the server. 89 | 90 | ```bash 91 | pg_ctl -D /home/postgres -l logfile stop 92 | ``` 93 | 94 | From a 5250 session, run WRKACTJOB and you should see the active server 95 | jobs and threads in the QUSRWRK subsystem 96 | 97 | ```text 98 | -------------------------------------------------------------------------------- 99 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 100 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 101 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 102 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 103 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 104 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 105 | QP0ZSPWP POSTGRES BCI .0 PGM-postgres SELW 106 | -------------------------------------------------------------------------------- 107 | ``` 108 | 109 | From a 5250 session, run `NETSTAT *CNN` to verify the server is listening on 110 | port 5432. You should see an entry for Local Port 5432 which tells you the 111 | server is listening for connections. 112 | 113 | ```text 114 | -------------------------------------------------------------------------------- 115 | Work with IPv4 Connection Status 116 | System: SYS1 117 | Type options, press Enter. 118 | 3=Enable debug 4=End 5=Display details 6=Disable debug 119 | 8=Display jobs 120 | 121 | Remote Remote Local 122 | Opt Address Port Port Idle Time State 123 | * * 5432 000:05:22 Listen 124 | -------------------------------------------------------------------------------- 125 | ``` 126 | 127 | From shell command line, create example pdatabase with the following command: 128 | 129 | ## Connect Client To the Server 130 | 131 | The `psql` command line client is a frontend to interact with PostgreSQL server 132 | backend. Lets use `psql` to connect to the server, create a database, create a 133 | table, insert data, and view the data. 134 | 135 | ```text 136 | $ psql 137 | Password for user postgres: 138 | postgres=# CREATE DATABASE us_states; 139 | CREATE DATABASE 140 | 141 | postgres=# \c us_states; 142 | You are now connected to database "us_states" as user "postgres". 143 | 144 | us_states=# CREATE TABLE States(id SERIAL, name varchar(50)); 145 | CREATE TABLE 146 | 147 | us_states=# INSERT INTO States(name) VALUES('Alabama'); 148 | INSERT 0 1 149 | 150 | us_states=# SELECT * FROM States; 151 | id | name 152 | ----+--------- 153 | 1 | Alabama 154 | (1 row) 155 | 156 | us_states=# \q 157 | ``` 158 | 159 | If you enabled remote connections, the same can be done using `psql` from a 160 | remote machine with: 161 | 162 | ```text 163 | $ psql -h myhost.example.com -U postgres -d us_states 164 | Password for user postgres: 165 | 166 | us_states=# INSERT INTO States(name) VALUES('Alaska'); 167 | INSERT 0 1 168 | us_states=# SELECT * FROM States; 169 | id | name 170 | ----+--------- 171 | 1 | Alabama 172 | 2 | Alaska 173 | (2 rows) 174 | 175 | us_states=# \q 176 | ``` 177 | 178 | Alternatively you can use a GUI client like pgAdmin, Heidi, DBeaver, etc to 179 | connect to Postgres server instead of `psql`. 180 | 181 | ```text 182 | Host: IBMi host name or IP 183 | Port: 5432 184 | User: postgres 185 | Password: Your password 186 | Database: us_states 187 | ``` 188 | 189 | ## Enable Remote Connections 190 | 191 | By default PostgreSQL only listens for client connections from localhost. 192 | To allow remote connection we need to configure some files. 193 | 194 | ***NOTE:*** [Secure connections with SSL](https://www.postgresql.org/docs/12/ssl-tcp.html#SSL-SETUP) 195 | if your server is accessible publicly. In this example the server protected 196 | behind a firewall. 197 | 198 | Before editing the configuration files make sure the PostgreSQL server is 199 | stopped with 200 | 201 | ```bash 202 | pg_ctl -D /home/postgres -l logfile stop 203 | ``` 204 | 205 | Use nano, vim or some other editor to edit ***/home/postgres/postgresql.conf*** 206 | file so the server will listen on TCP/IP addresses. We will enable access on all 207 | IP addresses 208 | 209 | ```text 210 | # listen_addresses = 'localhost' 211 | listen_addresses = '*' 212 | ``` 213 | 214 | ***NOTE:*** This will allow PostgreSQL server to listen for all IP addresses. 215 | 216 | Read the [docs](https://www.postgresql.org/docs/12/runtime-config-connection.html) 217 | for more details on Connection configuration. 218 | 219 | Edit the `IPv4 local connections` line in ***/home/postgres/pg_hba.conf*** 220 | 221 | ```text 222 | # IPv4 local connections: 223 | # TYPE DATABASE USER ADDRESS METHOD 224 | # host all all 127.0.0.1/32 scram-sha-256 225 | host all all 0.0.0.0/0 scram-sha-256 226 | ``` 227 | 228 | Read the [docs](https://www.postgresql.org/docs/12/auth-pg-hba-conf.html) for 229 | more details on ***pg_hba.conf*** configuration. 230 | 231 | ***NOTE:*** This will allow clients from any IPv4 address to authenticate. 232 | 233 | Start the PostgreSQL server with: 234 | 235 | ```bash 236 | pg_ctl -D /home/postgres -l logfile stop 237 | ``` 238 | 239 | Now that you have postgresql installed and setup refer to to the standard 240 | [PostgreSQL documentation](https://www.postgresql.org/docs/) as needed. 241 | -------------------------------------------------------------------------------- /python/INSTALLING_PYTHON_PKGS.md: -------------------------------------------------------------------------------- 1 | # Installing Python Packages 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | See [Python usage notes](./README.md) for basic information. 8 | 9 | ## General Guidance (always try RPM first!) 10 | For packages not listed in the above table, first check if it's available via 11 | yum. If so, it is recommended to install it through yum instead of installing 12 | it using pip. 13 | 14 | 15 | ### Installing native code with pip 16 | 17 | If you must install using pip, make sure to invoke pip correctly (see 18 | [Python usage notes](./README.md)) 19 | 20 | Also, you may need to install development tools, like gcc and automake, which you 21 | can often do a la carte (`yum install gcc automake`) or you may need to install 22 | the "Development Tools" group (`yum group install "Development Tools"`). 23 | 24 | You will also need to set the following environment variables for build: 25 | - `OBJECT_MODE=64` 26 | 27 | If you have issues that you cannot debug, feel free to join the community channels 28 | documented [here](http://ibm.biz/ibmioss)! 29 | -------------------------------------------------------------------------------- /python/README.md: -------------------------------------------------------------------------------- 1 | # Python usage notes 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | All things assume you have [PATH set correctly](../troubleshooting/SETTING_PATH.md). 8 | 9 | ## Which versions are available? 10 | Currently, Python versions 3.6 and 3.9 are available, 11 | via the `python3` and `python39` packages, respectively. 12 | 13 | **Important Note:** 14 | Performing a `yum upgrade` operation will not upgrade 15 | currently-installed versions of Python to a new major 16 | version. This would break existing apps. 17 | 18 | ## Python virtual environments (highly recommended!) 19 | ### 1. Installing system-wide packages 20 | Use `yum` to install any RPM-provided packages that you 21 | may use inside your virtual environment. 22 | 23 | ### 2. Creating a virtual environment 24 | **If using Python 3.9** 25 | ``` 26 | python3.9 -m venv --system-site-packages /path/to/venv 27 | ``` 28 | **If using Python 3.6** 29 | ``` 30 | python3.6 -m venv --system-site-packages /path/to/venv 31 | ``` 32 | ### 3. Entering and using the virtual environment 33 | To "enter" a virtual environment, run: 34 | ``` 35 | source /path/to/venv/bin/activate 36 | ``` 37 | Once completed, you should be able to run the `python` and `pip` commands. They will use the version of Python that was used to create the virtual environment. 38 | 39 | ## Which Python command to use outside of a virtual environment? 40 | ### Python interpreter 41 | 42 | **Use the versioned python command when feasible.** 43 | It is always best to run the fully-versioned python command, which is 44 | either `python3.9` or `python3.6`, since the `python` or 45 | `python3` commands may render different results depending 46 | on what packages are installed or what the current environment 47 | contains. 48 | 49 | **Alternatives if `python39` is not installed:** 50 | Use `python3.6`. One can alternatively use the shorthand 51 | `python3`, but including the major and minor version 52 | in the python command is more explicit and is best practice. 53 | For instance, launch your python program via: 54 | ``` 55 | python3.6 myprogram.py 56 | ``` 57 | 58 | **Alternatives if `python39` is installed:** 59 | Use `python3.9` or simply `python`, since the `python39` package 60 | creates a `python` via `update-alternatives`. 61 | ``` 62 | python3.9 myprogram.py 63 | ``` 64 | 65 | ### Preferred Installer for Python (pip) 66 | Invoke the Python interpreter command (above), followed 67 | by `-m pip`. For instance: 68 | ``` 69 | python3.9 -m pip install --upgrade xlsxwriter 70 | ``` 71 | 72 | ## Installing Python packages 73 | See [Installing Python Packages](INSTALLING_PYTHON_PKGS.md) 74 | 75 | ## Modules for accessing Db2, RPG, CL etc 76 | 77 | - Be sure to use the `itoolkit` package from PyPI (installable via pip) for accessing RPG, CL, etc. 78 | - For database access with `odbc`: 79 | - If running on IBM i: Install the `python3-pyodbc` or `python39-pyodbc` RPM package, depending on which version of Python you are using. This will be much easier than installing with `pip`, which will require you to compile these components. 80 | - If connecting remotely: Install `pyodbc` through any supported method, and use the IBM i Access ODBC driver. 81 | - See [the ODBC doc](../odbc/README.md) for further guidance on ODBC. 82 | - For database access with `ibm_db`: 83 | - If running on IBM i: Install the `python3-ibm_db` or `python39-ibm_db` RPM package, depending on which version of Python you are using. **DO NOT INSTALL WITH `pip`!! This will not work.** 84 | - If connecting remotely: Install the `ibm_db` package in any supported fashion. Db2 Connect licensing is required. 85 | 86 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | alabaster==0.7.12 2 | Babel==2.9.1 3 | certifi>=2023.7.22 4 | chardet==3.0.4 5 | commonmark==0.9.1 6 | docutils==0.16 7 | idna==2.10 8 | imagesize==1.2.0 9 | Jinja2==2.11.3 10 | MarkupSafe==1.1.1 11 | myst-parser==0.17.2 12 | packaging==20.4 13 | Pygments==2.16.1 14 | pyparsing==2.4.7 15 | pytz==2020.1 16 | requests>=2.25.1 17 | six==1.15.0 18 | snowballstemmer==2.0.0 19 | Sphinx==3.2.1 20 | sphinx-rtd-theme==0.5.0 21 | sphinxcontrib-applehelp==1.0.2 22 | sphinxcontrib-devhelp==1.0.2 23 | sphinxcontrib-htmlhelp==1.0.3 24 | sphinxcontrib-jsmath==1.0.1 25 | sphinxcontrib-qthelp==1.0.3 26 | sphinxcontrib-serializinghtml==1.1.4 27 | urllib3==1.26.18 28 | sphinx-reredirects==0.0.1 29 | -------------------------------------------------------------------------------- /tls/README.md: -------------------------------------------------------------------------------- 1 | # TLS Setup 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Best practices 8 | 9 | It is often considered best practice to not handle TLS encryption within the application (for 10 | instance, your Node.js or Python aplication). 11 | Instead, handle the TLS setup in a separate HTTP server that runs in front of your application. 12 | The two most reasonable options for this are NGINX and Apache (IBM i HTTP server). 13 | 14 | You may choose to use [LetsEncrypt and/or CertBot](../certbot.md) to generate production-ready 15 | certificates. 16 | 17 | ## Creating a self-signed certificate 18 | 19 | Run the following steps to generate a self-signed certificate for development (not production): 20 | 21 | ```openssl 22 | openssl genrsa -out my-key.pem 2048 23 | openssl req -new -sha256 -key my-key.pem -out my-csr.pem 24 | openssl x509 -req -in my-csr.pem -signkey my-key.pem -out my-cert.pem 25 | ``` 26 | 27 | ## Setting up TLS with NGINX (uses OpenSSL) 28 | 29 | See [the NGINX notes](../nginx.md). 30 | 31 | ## Setting up IBM i HTTP Server (uses Digital Certificate Manager) 32 | 33 | See [this article on MC Press Online](https://www.mcpressonline.com/operating-systems/ibm-i-os400-i5os/using-apache-as-a-reverse-proxy-on-ibm-i) 34 | for information on using IBM i HTTP Server (Apache) as a reverse proxy. Then, 35 | simply configure TLS as you would for other IBM i servers in Digital Certificate 36 | Manager (DCM). See [this IBM support document](https://www.ibm.com/support/pages/digital-certificate-manager-dcm-frequently-asked-questions-and-common-tasks), 37 | particularly the "How do I configure an HTTP server for SSL?" section for more information on 38 | the steps needed to configure DCM. 39 | 40 | ## Want to handle TLS in the application anyway? 41 | 42 | If you still wish to handle TLS in the application (perhaps for development purposes), be aware that: 43 | - Configuration for the IBM i will generally be the same as on other platforms. 44 | - Digital Certificate Manager (DCM) is not used (you can, however, export the certificate from DCM for 45 | use with your application). 46 | 47 | So, for example, when configuring a Node.js server for TLS, you can reference the 48 | [Node.js documentation on HTTPS](https://nodejs.org/api/https.html). If using a web framework, that 49 | framework's documentation will often have useful information and examples. 50 | -------------------------------------------------------------------------------- /troubleshooting/5733OPS_MIGRATION.md: -------------------------------------------------------------------------------- 1 | # Guide to migrating from 5733-OPS to RPMs 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Environment setup (PATH) 8 | 9 | By default, the RPM-form packages do not create symbolic links in standard, 10 | used-by-default directories like `/QOpenSys/usr/bin/` or `/usr/bin/`. 11 | 12 | To address this, [Set the PATH environment variable](SETTING_PATH.md) so that 13 | your shell will find the new commands when you try to run them. 14 | ## Modifying scripts to use an appropriate "shebang" (#!) line 15 | 16 | When writing a shell script (or a Python/Node.js program), it is common practice 17 | to start your source code with a "shebang" line(`#!`). This tells the shell what 18 | program to use when the script is run. 19 | 20 | To properly use RPM-form executables, there are two options for making sure the 21 | scripts use the RPM form, and not 5733-OPS. 22 | 23 | The first (and most industry-standard) technique is to use the special 24 | `/usr/bin/env` command in the shebang line, followed by the program that is 25 | interpreting the script. This will look in your PATH for the named executable. 26 | Thus, it is very important that your PATH be set correctly!!! For instance, for 27 | a bash script: 28 | 29 | ``` bash 30 | #!/usr/bin/env bash 31 | echo "starting my shell script" 32 | ``` 33 | 34 | Another approach is to fully-qualify the path to the binary in 35 | `/QOpenSys/pkgs/bin`. For instance: 36 | 37 | ``` bash 38 | #!/QOpenSys/pkgs/bin/bash 39 | echo "starting my shell script" 40 | ``` 41 | 42 | These techniques can apply to more than just shell scripts, and can be used for 43 | other interpreted languages such as perl or Python. For example, here's how the 44 | shebang line would look for a `python3.9` program with the `/usr/bin/env` method 45 | 46 | ``` python3 47 | #!/usr/bin/env python3.9 48 | print("starting my python program") 49 | ``` 50 | 51 | And with the fully-qualified technique: 52 | 53 | ``` python3 54 | #!/QOpenSys/pkgs/bin/python3.9 55 | print("starting my python program") 56 | ``` 57 | 58 | ## Python migration notes 59 | 60 | See [Python usage notes](../python/README.md) 61 | 62 | ## Node.js migration notes 63 | 64 | See [Node.js usage notes](../nodejs/README.md) 65 | -------------------------------------------------------------------------------- /troubleshooting/README.md: -------------------------------------------------------------------------------- 1 | # Common Open Source Problems (and how to fix them) 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## Things to always check first when troubleshooting 8 | 9 | The first step in troubleshooting is to ensure that 10 | all of the following are true: 11 | - You are accessing the system with an SSH terminal 12 | - If you insist on using 5250, favor QP2TERM over 13 | QSH. If using QSH, ensure that the `QIBM_MULTI_THREADED` 14 | environment variable is set to `Y` **before** 15 | launching QSH 16 | - If you insist on using 5250, be aware that you 17 | are more likely to have problems, even if the 18 | above precautions are taken. 19 | - You have your `PATH` environment variable set properly. 20 | See [Setting your PATH](SETTING_PATH.md) for guidance. 21 | - You are only editing files with only ASCII or UTF8-based 22 | editors, such as: 23 | - (Recommended) A cross-platform editor such as VSCode, 24 | Notepad++, jEdit, etc. 25 | - an SSH terminal UI-based editor, such as vim, nano, 26 | or jmacs. 27 | - You don't have CRLF line terminators in your files. This 28 | can happen if you have edited your file from Windows and 29 | do not have your editor properly configured. If you 30 | are unsure, install the `dos2unix` package and run 31 | the resulting `dos2unix` utility on your file. 32 | 33 | ## Shell cannot find yum command 34 | 35 | When running the `yum` command from the command line, you encounter an error like: 36 | 37 | - `-bash: yum: command not found` 38 | - `yum: not found` 39 | - `ksh: yum: not found` 40 | - `qsh: 001-0019 Error found searching for command yum. No such path or directory.` 41 | 42 | **Solution:** 43 | 44 | Add `/QOpenSys/pkgs/bin` to the beginning of your PATH environment variable. See 45 | [Setting your PATH](SETTING_PATH.md) for details 46 | 47 | Also, please don't use QSH for open source tools. Use an SSH terminal instead. 48 | 49 | ## yum connectivity issues 50 | 51 | See [this doc](YUM.md) 52 | 53 | ## yum can't connect to the repository (with thread error) 54 | 55 | When running yum from QSH, any commands that connect to the repository (install 56 | upgrade, etc) fail with a message like so: 57 | 58 | ```sh 59 | yum install python3 60 | https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo/repodata/repomd.xml: [Errno 14] curl#6 - "getaddrinfo() thread failed to start" 61 | Trying other mirror. 62 | Error: Cannot retrieve repository metadata (repomd.xml) for repository: ibm. Please verify its path and try again 63 | ``` 64 | 65 | **Solution:** 66 | 67 | Run yum via SSH or the ACS Open Source Package Manager GUI. These are the ideal 68 | interfaces for working with yum and the rest of the open source ecosystem. 69 | 70 | If you need to work from 5250, QP2TERM is preferred over QSH, but QSH _will_ 71 | work as long as the `QIBM_MULTI_THREADED` environment variable is set to `Y` at 72 | the job level. 73 | 74 | ## Up arrow doesn't recall previous commands 75 | 76 | Using arrow keys in the shell causes "garbage" to be displayed on the screen 77 | instead of cycling through command history (eg. `^[[A^[[D^[[C^[[C^[[D^[[A`) 78 | 79 | **Solution:** 80 | 81 | The default shell used by SSH is `bsh`, which is very primitive. You will 82 | probably want to set `bash` as your default shell. See 83 | [Setting bash as your shell](SETTING_BASH.md) for details. 84 | 85 | 86 | ## User input is not working properly when running in 5250 87 | 88 | Generally speaking, **open source programs do not work well in 5250 interfaces** 89 | such as QSH or Qp2Term. This may result in improper processing of control keys, 90 | phantom user input from previous commands, "garbage" characters printed to the 91 | screen, or a host of other issues. This strange behavior can affect `bash` or 92 | any open source software. 93 | 94 | There may also be issues with process groups and job control. In particular, 95 | attempts to run `bash` in a 5250 environment may result in an error similar to 96 | the following: 97 | ``` 98 | bash: cannot set terminal process group (1319667): A system call received a parameter that is not valid. 99 | bash: no job control in this shell 100 | ``` 101 | 102 | **Solution:** 103 | 104 | Please use an SSH terminal emulator and an SSH connection. Also, for usability, 105 | you probably want to set `bash` as your default shell. See 106 | [Setting bash as your shell](SETTING_BASH.md) for details. 107 | 108 | ## Python can't find packages installed from ACS 109 | 110 | After installing a Python package from ACS (eg. `python3-Pillow`), it can't be found. 111 | 112 | **Solution:** 113 | 114 | - Ensure you are running the correct version of Python for the package that was 115 | installed: `python3` for packages with the `python3` prefix and `python2` for 116 | packages with the `python2` prefix. 117 | - Also ensure that your `PATH` environment variable is set to find 118 | `/QOpenSys/pkgs/bin` before `/QOpenSys/usr/bin` and `/usr/bin`, especially if 119 | you potentially have other Pythons installed from 5733-OPS or Perzl rpms. See 120 | [Setting your PATH](SETTING_PATH.md) for details. 121 | 122 | *NOTE: neither `python` rpm installed via yum creates a `python` symlink, so you 123 | cannot just run `python`.* 124 | 125 | ## Yum or RPM fails with "Error: Error: rpmdb open failed" 126 | 127 | When Running a `yum` or `rpm` command you encounter 128 | 129 | ```text 130 | Error: Error: rpmdb open failed 131 | ``` 132 | 133 | **Solution:** 134 | 135 | The rpm database has gotten corrupted. Please report this issue [here](http://ibm.biz/ibmi-rpm-issue-tracker). 136 | 137 | The common solution is to rebuild the database with 138 | 139 | ```sh 140 | /QOpenSys/pkgs/bin/rpm --rebuilddb 141 | ``` 142 | 143 | ## Yum or RPM fails with "db4 error(19) from dbenv->open: The specified device does not exist." 144 | 145 | Running yum you encounter an error like 146 | 147 | ```text 148 | error: db4 error(19) from dbenv->open: The specified device does not exist. 149 | error: cannot open Packages index using db4 - The specified device does not exist. (19) 150 | error: cannot open Packages database in /QOpenSys/var/lib/rpm 151 | CRITICAL:yum.main: 152 | Error: rpmdb open failed 153 | ``` 154 | 155 | You probably have journalling on for an IFS directory that rpm is using. rpm 156 | uses `mmap` to open its database files, which is incompatible with journaling. 157 | 158 | *Note: When an ILE a application tries to `mmap` an IFS file which is being 159 | journaled it gets an error - `ENOTSUP` (operation not supported), however this 160 | gets mapped to PASE as `ENODEV` (no such device) which makes things confusing.* 161 | 162 | **Solution:** 163 | 164 | Ensure that journaling is disabled/omitted for `/QOpenSys/var/lib/rpm` or any 165 | subdirectory. You can use option 8 from `WRKLNK` to view the journaling 166 | attributes of a given file or directory. 167 | 168 | ## Commands are failing in QSH 169 | 170 | Many commands will fail in QSH for many reasons! However, a common reason is related 171 | to the QSH behavior that disallows multithreaded applications by default. The resulting 172 | error message may or may not be descriptive, but here are some examples. 173 | 174 | git: 175 | ```text 176 | error: cannot create async thread: Resource temporarily unavailable 177 | fatal: fetch-pack: unable to fork off sideband demultiplexer 178 | ``` 179 | 180 | node/npm: 181 | ```text 182 | [335708]: ../src/node_platform.cc:61:std::unique_ptr node::Work erThreadsTaskRunner::DelayedTaskScheduler::Start(): Assertion `(0) == (uv_thr ead_create(t.get(), start_thread, this))' failed. 183 | qsh: 001-0078 Process ended by signal 5. 184 | ``` 185 | 186 | curl: 187 | ```text 188 | curl: (6) getaddrinfo() thread failed to start 189 | ``` 190 | 191 | java (openjdk): 192 | ```text 193 | Error: Port Library failed to initialize: -1 194 | Error: Could not create the Java Virtual Machine. 195 | Error: A fatal exception has occurred. Program will exit. 196 | ``` 197 | 198 | **Solution:** 199 | 200 | As mentioned earlier, the optimal solution is to connect with an SSH client. 201 | If you insist on using 5250, favor QP2TERM over QSH. If using QSH,you must 202 | ensure that the `QIBM_MULTI_THREADED` environment variable is set to `Y` 203 | **before** launching QSH. 204 | 205 | ## Ansible fails with "No python interpreters found" 206 | 207 | If running Ansible against an IBM i endpoint, it can sometimes fail with 208 | the following warning issued: 209 | 210 | ``` 211 | [WARNING]: No python interpreters found for host __________ (tried ['/usr/bin/python', 'python3.7', 'python3.6', 'python3.5', 'python2.7', 'python2.6', '/usr/libexec/platform-python', '/usr/bin/python3', 'python']) 212 | ``` 213 | 214 | This is because Ansible does not currently know how to find the RPM-installed 215 | Python interpreters on IBM i 216 | (GitHub [issue](https://github.com/ansible/ansible/issues/77458) pending). 217 | 218 | **Solution:** 219 | 220 | This can often be corrected by [fixing the PATH](./SETTING_PATH.md) of the user 221 | that you are using to connect with Ansible. 222 | 223 | It's likely best, however, to be more explicit, so you're not as susceptible 224 | to variations in server environments. To do so, you can set Ansible's 225 | `ansible_python_interpreter` inventory variable to a fully-qualified path, 226 | namely `/QOpenSys/pkgs/bin/python3.9` (use version 3.6 if absolutely needed). 227 | This can be done in the various ways. See 228 | [this doc](https://docs.ansible.com/ansible/latest/reference_appendices/python_3_support.html). 229 | 230 | ## Ansible (or another SSH-based tool) asks for a password 231 | 232 | If you'd like to run Ansible (or similar SSH-based tools) non-interactively and 233 | without a password, it can sometimes still ask for a user password (and 234 | therefore fail in non-interactive environments). 235 | 236 | **Solution:** 237 | 238 | You need to configure password-less authentication per 239 | [this doc](../user_setup/README.md), just use the same Linux and IBM i system 240 | and user. Alternatively, once you install your public key on the IBM i server, 241 | provide your private key to ansible by way of the 242 | `ansible_ssh_private_key_file` inventory variable. More info 243 | [here](https://docs.ansible.com/ansible/latest/user_guide/connection_details.html). 244 | **Always make sure that your private key is kept secure!** 245 | 246 | ## "intended for a different operating system" when running IBM i 7.4 247 | If you installed the open source "bootstrap" from a very early version, and have since 248 | upgraded to IBM i 7.4, you may see errors like the following when trying to 249 | install a package: 250 | 251 | ```fortran 252 | Transaction Check Error: 253 | package make-gnu-4.2-2.ppc64 is intended for a different operating system 254 | ``` 255 | 256 | **Solution:** 257 | 258 | The very early versions of the bootstrap did not know IBM i 7.4 existed. You can work 259 | around this issue by adding an OS compatibility setting to the RPM configuration, 260 | as shown in the following command: 261 | 262 | ```bash 263 | echo 'os_compat: ibmi7.4: ibmi ibmi7.1 ibmi7.2 ibmi7.3' >> /QOpenSys/pkgs/lib/rpm/rpmrc 264 | ``` 265 | 266 | It is then recommended to get the latest versions of `rpm`, `yum`, and `ibmi-repos` 267 | packages: 268 | 269 | ```bash 270 | /QOpenSys/pkgs/bin/yum install -y rpm yum ibmi-repos 271 | ``` 272 | 273 | ## rsync from another system fails with `rsync: not found` 274 | 275 | When using rsync from another operating system (Linux, for instance), rsync may be 276 | unable to locate the `rsync` executable on IBM i and will therefore fail. The error 277 | message may resemble something like this: 278 | 279 | ```fortran 280 | bsh: rsync: not found 281 | rsync: connection unexpectedly closed (0 bytes received so far) [sender] 282 | rsync error: error in rsync protocol data stream (code 12) at io.c(228) [sender=3.2.3] 283 | ``` 284 | 285 | **Solution #1 (recommended):** 286 | 287 | Install the `rsync-compat` package on your IBM i system. 288 | 289 | ```fortran 290 | /QOpenSys/pkgs/bin/yum install rsync-compat 291 | ``` 292 | 293 | 294 | **Solution #2 (adjust your PATH):** 295 | 296 | First, make sure that the `rsync` RPM package is installed on IBM i. 297 | Ensure that the `PATH` environment variable is set to include the `/QOpenSys/pkgs/bin` path. 298 | The most prescriptive technique for doing so is documented [here](SETTING_PATH.md). Note that 299 | bash-specific approaches (use of .bash_profile, for instance) will not work if your default 300 | shell is `bsh` or some other non-bash option. 301 | 302 | **Solution #3 (explicitly set remote rsync path):** 303 | 304 | First, make sure that the `rsync` RPM package is installed on IBM i. 305 | When invoking the rsync command, use the following option on the command line: 306 | 307 | ```fortran 308 | --rsync-path=/QOpenSys/pkgs/bin/rsync 309 | ``` 310 | 311 | For instance: 312 | ```fortran 313 | rsync --rsync-path=/QOpenSys/pkgs/bin/rsync -a src user@ibmiserver:/path/to/destination 314 | ``` 315 | 316 | ## I'm still having issues 317 | 318 | If you are having an issue that's not listed above or the solution provided did 319 | not help, please open a ticket [here](http://ibm.biz/ibmi-oss-issues). 320 | -------------------------------------------------------------------------------- /troubleshooting/SETTING_BASH.md: -------------------------------------------------------------------------------- 1 | # Setting BASH as your shell 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ***The bash shell can (and should!) be your default shell for when you connect 8 | with an SSH session. SSH connections are recommended for open source tools. 9 | This will not affect the shell in use by non-SSH shell environments, such as 10 | CALL QP2TERM or STRQSH*** 11 | 12 | First, install open source environment and [yum](../yum/README.md). Make sure 13 | the `bash` package is installed (it should be, by default). After doing so, you 14 | can set `bash` to be your default shell via one of the following techniques: 15 | 16 | ## Technique #1: chsh 17 | 18 | 1. Use yum to install the `chsh` package (for instamce, `yum install chsh`) 19 | 20 | 2. From a shell, use the `chsh` command to set your shell 21 | (for instance, `/QOpenSys/pkgs/bin/chsh -s /QOpenSys/pkgs/bin/bash`). 22 | You can set the shell for another user via the `-u` option 23 | (for instance, `/QOpenSys/pkgs/bin/chsh -s /QOpenSys/pkgs/bin/bash -u otherusr`). 24 | 25 | ## Technique #2: sql 26 | 27 | You can set bash to be your default shell by running the following command from 28 | anywhere you have an SQL context, such as the Run SQL Scripts tool: 29 | 30 | ```SQL 31 | CALL QSYS2.SET_PASE_SHELL_INFO('*CURRENT', '/QOpenSys/pkgs/bin/bash') 32 | ``` 33 | 34 | You can also set bash to be the default shell for all users, by running: 35 | 36 | ```SQL 37 | CALL QSYS2.SET_PASE_SHELL_INFO('*DEFAULT', '/QOpenSys/pkgs/bin/bash') 38 | ``` 39 | 40 | Or, for a specific user: 41 | 42 | ```SQL 43 | CALL QSYS2.SET_PASE_SHELL_INFO('OTHRUSR', '/QOpenSys/pkgs/bin/bash') 44 | ``` 45 | 46 | More information on this IBM i service can be found on [developerWorks](https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20i%20Technology%20Updates/page/QSYS2.SET_PASE_SHELL_INFO%20Procedure) 47 | 48 | Also, the default shell setting can be queried out with [QSYS2.USER_INFO](https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20i%20Technology%20Updates/page/QSYS2.USER_INFO%20catalog) 49 | 50 | # See also 51 | 52 | You will also want to make sure your `PATH` is set up correctly, if you 53 | have not yet done so. See [these docs](./SETTING_PATH.md). -------------------------------------------------------------------------------- /troubleshooting/SETTING_PATH.md: -------------------------------------------------------------------------------- 1 | # Adjusting your PATH temporarily 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | Temporarily adjust your path by running the following two commands: 8 | 9 | ```bash 10 | PATH=/QOpenSys/pkgs/bin:$PATH 11 | export PATH 12 | ``` 13 | 14 | After that, typing commands should find RPM-installed open source tools 15 | (if using bash already, you may need to run `hash -r`, like the following example 16 | 17 | ```bash 18 | $ bash --version 19 | GNU bash, version 4.4.12(1)-release (powerpc-ibm-os400) 20 | Copyright (C) 2016 Free Software Foundation, Inc. 21 | License GPLv3+: GNU GPL version 3 or later 22 | 23 | This is free software; you are free to change and redistribute it. 24 | There is NO WARRANTY, to the extent permitted by law. 25 | ``` 26 | 27 | ## HIGHLY Recommended: adjust your PATH permanently 28 | 29 | If you want to make your `PATH` setting permanent, add the above line to your 30 | `$HOME/.profile` and/or your `$HOME/.bash_profile` (if you are using bash). 31 | You can do this easily (from a shell) like so. 32 | 33 | ```bash 34 | touch $HOME/.profile 35 | setccsid 1208 $HOME/.profile 36 | echo 'PATH=/QOpenSys/pkgs/bin:$PATH' >> $HOME/.profile 37 | echo 'export PATH' >> $HOME/.profile 38 | ``` 39 | 40 | To make this change for all users, put these lines in `/QOpenSys/etc/profile`, 41 | like so: 42 | 43 | ```bash 44 | touch /QOpenSys/etc/profile 45 | setccsid 1208 /QOpenSys/etc/profile 46 | echo 'PATH=/QOpenSys/pkgs/bin:$PATH' >> /QOpenSys/etc/profile 47 | echo 'export PATH' >> /QOpenSys/etc/profile 48 | ``` 49 | 50 | **Need to run globally-installed Node.js modules, 51 | or choose a Node.js version on a per-user basis?** 52 | 53 | To run `node-gyp` or other globally-installed modules, or to switch the default 54 | version of Node.js for a specific user, place `/QOpenSys/pkgs/lib/nodejs/bin` 55 | at the beginning of the user's PATH environment variable. For instance, that user 56 | could run the following from the shell to set their default to version 10: 57 | 58 | ```bash 59 | touch $HOME/.profile 60 | setccsid 1208 $HOME/.profile 61 | echo 'PATH=/QOpenSys/pkgs/lib/nodejs10/bin:/QOpenSys/pkgs/bin:$PATH' >> $HOME/.profile 62 | echo 'export PATH' >> $HOME/.profile 63 | ``` 64 | 65 | (if using `bash` as the shell, the user may need to run `hash -r`) 66 | 67 | ## Verifying that your PATH is set correctly 68 | Simply run the following from your operating environment: 69 | ```bash 70 | echo $PATH 71 | ``` 72 | The output should be a `:`-delimited list of directories. 73 | These will be searched, in order, for any commands entered 74 | into your shell. The `PATH` should contain, at minimum, 75 | `/QOpenSys/pkgs/bin`, very preferrably before the "standard" 76 | paths like `/QOpenSys/usr/bin` or `/usr/bin`. You may also 77 | see other PATHS you added to the beginning, for instance, 78 | to choose a Node.js version per the 79 | [Node.js usage notes](../nodejs/README.md) 80 | 81 | For example: 82 | **Horrible** 83 | ```bash 84 | /usr/bin:.:/QOpenSys/usr/bin 85 | ``` 86 | 87 | **Bad** 88 | ```bash 89 | /QOpenSys/usr/bin:/usr/ccs/bin:/QOpenSys/usr/bin/X11:/usr/sbin:.:/usr/bin 90 | ``` 91 | 92 | **Marginal** 93 | ```bash 94 | /QOpenSys/usr/bin:/usr/ccs/bin:/QOpenSys/usr/bin/X11:/usr/sbin:.:/usr/bin:/QOpenSys/pkgs/bin 95 | ``` 96 | **Best** 97 | ```bash 98 | /QOpenSys/pkgs/bin:/QOpenSys/usr/bin:/usr/ccs/bin:/QOpenSys/usr/bin/X11:/usr/sbin:.:/usr/bin 99 | ``` 100 | -------------------------------------------------------------------------------- /troubleshooting/YUM.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting Yum connection problems 2 | 3 | This page is designed to help you do problem determination for scenarios where yum itself is not working 4 | due to connection problems. That is, you are having trouble getting RPM packages installed. 5 | 6 | There are several `yum` problems that may not be connection related, and those are documented 7 | on [the main troubleshooting page](README.md) 8 | 9 | ## Before you go further... make sure you have `ibmi-repos` installed 10 | 11 | To make sure you're seeing the latest updates available for your operating system, make sure you have 12 | the latest version of `yum` and `ibmi-repos` installed, if you are able to. 13 | ``` 14 | /QOpenSys/pkgs/bin/yum upgrade yum ibmi-repos 15 | ``` 16 | 17 | Once the `ibmi-repos` package is installed, you may need to upgrade again to make sure you are at the 18 | latest version available for your release: 19 | ``` 20 | /QOpenSys/pkgs/bin/yum upgrade ibmi-repos 21 | ``` 22 | 23 | If you are able to successfully install the `ibmi-repos` package, you can consider removing the 24 | legacy repo definition by running: 25 | 26 | ``` 27 | mv /QOpenSys/etc/yum/repos.d/ibm.repo /QOpenSys/etc/yum/repos.d/ibm.repo.backup 28 | ``` 29 | 30 | If you cannot install the `ibmi-repos` package, for some reason, you can try using http: 31 | 32 | ``` 33 | /QOpenSys/pkgs/bin/yum-config-manager --setopt=ibm.baseurl=http://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo 34 | ``` 35 | 36 | Or ftp: 37 | 38 | ``` 39 | /QOpenSys/pkgs/bin/yum-config-manager --setopt=ibm.baseurl=http://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo 40 | ``` 41 | 42 | 43 | # Checking Connectivity 44 | 45 | The most common cause of issue with yum is related to network connectivity. Errors will state something like 46 | ``` 47 | unable to open repomd.xml 48 | ``` 49 | 50 | The IBM server supports three protocols for downloading packages: 51 | - HTTPs (secure, default, recommended) 52 | - HTTP (disabled by default) 53 | - FTP (disabled by default) 54 | 55 | HTTP or FTP can be used as a backup mechanism if you are unable to get the default configuration working, or if your network 56 | prohibits https connections. 57 | 58 | You can use Python to check connectivity to the IBM RPM server. To check if you have HTTPS connectivity and have proper 59 | TLS setup, run: 60 | 61 | ```python 62 | /QOpenSys/pkgs/bin/python2.7 -c "import socket; import ssl; hostname='public.dhe.ibm.com'; ssl.create_default_context().wrap_socket(socket.create_connection((hostname,443), 30), server_hostname=hostname) ; print 'success'" 63 | ``` 64 | 65 | The output from this command can help you figure out next steps: 66 | - If the output contains `Hostname and service name not provided or found`, DNS is not configured properly 67 | - If the output contains `timed out` or `connection refused` then you cannot reach IBM's server 68 | - If the output contains `ssl.CertificateError: hostname '______________' doesn't match 'public.dhe.ibm.com'`, a separate entity is injecting an SSL certificate 69 | - If the output contains another CertificateError, you need to install the `ca-certificates-mozilla` package 70 | 71 | ## Checking Connectivity for alternative protocols 72 | 73 | Occasionally, you can use alternative protocols (http, ftp, or https without TLS verification) to circumvent connectivity issues. 74 | 75 | 76 | **To check if you have HTTPs connectivity (without TLS verification):** 77 | 78 | ```python 79 | /QOpenSys/pkgs/bin/python2.7 -c "import socket; socket.create_connection(('public.dhe.ibm.com', 443), 30); print 'success'" 80 | ``` 81 | 82 | **To check for HTTP connectivity** 83 | 84 | ```python 85 | /QOpenSys/pkgs/bin/python2.7 -c "import socket; socket.create_connection(('public.dhe.ibm.com', 80), 30); print 'success'" 86 | ``` 87 | 88 | **To check for FTP connectivity:** 89 | 90 | ```python 91 | /QOpenSys/pkgs/bin/python2.7 -c "import socket; socket.create_connection(('public.dhe.ibm.com', 21), 30); print 'success'" 92 | ``` 93 | 94 | The output from this command can help you figure out next steps: 95 | - If the output contains `Hostname and service name not provided or found`, DNS is not configured properly 96 | - If the output contains `timed out` or `connection refused` then you cannot reach IBM's server 97 | 98 | 99 | ### DNS not configured properly 100 | 101 | If DNS is not configured properly, please work with your IBM i system administrator or networking team to resolve the problem correctly. 102 | 103 | As a stopgap workaroud, you can create a host table entry for the IBM server at `public.dhe.ibm.com`. 104 | 105 | **Important Note: This IP address may change in the future. At which point, yum will start failing and you will need to create new host table entries** 106 | 107 | From SSH or QP2TERM: 108 | ``` 109 | system "ADDTCPHTE INTNETADR('129.35.224.112') HOSTNAME((public.dhe.ibm.com))" 110 | ``` 111 | 112 | From 5250 CL: 113 | ``` 114 | ADDTCPHTE INTNETADR('129.35.224.112') HOSTNAME((public.dhe.ibm.com)) 115 | ``` 116 | 117 | ### Cannot reach IBM's server with any protocol 118 | 119 | Please work with your networking team to resolve the problem. 120 | 121 | ### A separate entity is enjecting an SSL certificate 122 | 123 | Follow [these steps](https://www.seidengroup.com/2021/04/26/how-to-validate-self-signed-ssl-tls-certificates-from-ibm-i/) 124 | to add the new certificate as needed. 125 | 126 | ## Temporarily disabling SSL verification to install ca-certificates-mozilla 127 | 128 | To resolve certificate validation errors, usually installing ca-certificate-mozilla will resolve it, but if HTTPS is broken you can't install it resulting in a Catch-22. Temporarily disabling SSL verification can resolve the Catch-22 and allow you to install ca-certificates-mozilla. 129 | 130 | If you have the `ibmi-repos` package installed: 131 | 132 | ``` 133 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibmi-base.sslverify=0 134 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibmi-release.sslverify=0 135 | ``` 136 | Otherwise: 137 | 138 | ``` 139 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibm.sslverify=0 140 | ``` 141 | 142 | Then, proceed to install the `ca-certificates-mozilla` package 143 | 144 | Then, set the `sslverify` property back to `1`. To do so, If you have the `ibmi-repos` package installed: 145 | 146 | ``` 147 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibmi-base.sslverify=1 148 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibmi-release.sslverify=1 149 | ``` 150 | Otherwise: 151 | 152 | ``` 153 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibm.sslverify=1 154 | ``` 155 | 156 | 157 | ## Other Networking problems 158 | 159 | ### Operation too slow 160 | 161 | Sometimes, corporate network firewalls don't explicitly block ports, but they can drastically interfere with 162 | traffic throughput, resulting in: 163 | 164 | ``` 165 | 'Operation too slow. Less than 1000 bytes/sec transferred the last 30 seconds' 166 | ``` 167 | 168 | You can try working around this issue by enabling alternative protocols. 169 | 170 | ## Enabling alternative protocols 171 | 172 | Assuming you have a modern version of `ibmi-repos` installed, you can try connecting with http or ftp if https does not work. To enable http and ftp mirrors: 173 | ``` 174 | /QOpenSys/pkgs/bin/yum-config-manager --enable-repo=ibmi-base-unsecure 175 | /QOpenSys/pkgs/bin/yum-config-manager --enable-repo=ibmi-release-unsecure 176 | ``` 177 | (note this is unsecure and should be a temporary workaround until the http protocol issue is resolved by your networking team) 178 | 179 | ## Debug tool 180 | 181 | You can download [this debug tool](https://raw.githubusercontent.com/ThePrez/IBMiOSS-utils/master/yum_conncheck.py), save it to IFS, 182 | and run 183 | ``` 184 | /QOpenSys/pkgs/bin/python2.7 yum_conncheck.py 185 | ``` 186 | It will provide guidance 187 | 188 | ## TL;DR Steps that will fix most people that have a working DNS setup 189 | 190 | If you have `ibmi-repos` installed 191 | ``` 192 | /QOpenSys/pkgs/bin/yum-config-manager --disable-repo=ibm 193 | /QOpenSys/pkgs/bin/yum-config-manager --enable-repo=ibmi-base-unsecure 194 | /QOpenSys/pkgs/bin/yum-config-manager --enable-repo=ibmi-release-unsecure 195 | /QOpenSys/pkgs/bin/yum install ca-certificates-mozilla 196 | /QOpenSys/pkgs/bin/yum-config-manager --disable-repo=ibmi-base-unsecure 197 | /QOpenSys/pkgs/bin/yum-config-manager --disable-repo=ibmi-release-unsecure 198 | /QOpenSys/pkgs/bin/yum upgrade ibmi-repos 199 | ``` 200 | 201 | If you do not have `ibmi-repos` installed 202 | ``` 203 | /QOpenSys/pkgs/bin/yum-config-manager --save --setopt=ibm.sslverify=0 204 | /QOpenSys/pkgs/bin/yum install ca-certificates-mozilla ibmi-repos 205 | /QOpenSys/pkgs/bin/yum-config-manager --disable-repo=ibm 206 | ``` 207 | 208 | ## What if I cannot access the Internet from my IBM i system? 209 | 210 | Doc forthcoming... 211 | -------------------------------------------------------------------------------- /user_setup/README.md: -------------------------------------------------------------------------------- 1 | # Setting up a User's Environment 2 | 3 | As referenced in [our troubleshooting guide](../troubleshooting/README.md) 4 | and throughout this document, the recommended way to access 5 | most open source tools is by way of using an SSH terminal. 6 | [This blog entry](https://techchannel.com/SMB/08/2017/embrace-ssh), 7 | although a bit dated, summarizes some of the benefits. 8 | 9 | **It is not recommended to use a 5250 interface for running open source 10 | tools!** 11 | 12 | This document intends to walk you through the process of initializing 13 | environment to use SSH efficiently. 14 | 15 | This document also assumes your system administrator has installed the 16 | open source toolset on IBM i as documented [here](../yum/README.md). 17 | 18 | ```{toctree} 19 | :maxdepth: 1 20 | ``` 21 | 22 | ## Step 1: Install an SSH client 23 | 24 | There are many free SSH terminal emulators on the market. For the most part, 25 | any of these choices will serve you well. Here is a non-exhaustive list 26 | of options: 27 | 28 | For Windows users: 29 | - PuTTY 30 | - Windows Subsystem for Linux (WSL) 31 | - git bash 32 | - Cygwin (ensure the "openssh" package is selected during installation) 33 | 34 | For Mac/Linux users, the "ssh" command is often already installed. To verify, 35 | just open up a terminal window and run: 36 | 37 | ```bash 38 | ssh --version 39 | ``` 40 | 41 | ## Step 2: Create your first connection to the system 42 | 43 | If using one of the other options, your steps are generally to first open up 44 | a terminal window. 45 | On Windows, this varies based on which tool you are using. For instance: 46 | - WSL: press `+r` and type `bash` 47 | - git bash: press `` and search apps for `git bash` 48 | - Cygwin: press `` and search apps for `Cygwin64 Terminal` 49 | - PuTTY: See [these steps (external link)]([PUTTY_CONFIGURE_CONNECTION.md](https://cuit.columbia.edu/putty)) for more info. 50 | 51 | Once a terminal window is open, connect to the IBM i system with the following 52 | command: 53 | 54 | ```ssh 55 | ssh user@system 56 | ``` 57 | 58 | (Of course, replace `user` with your user profile, and `system` with the host 59 | name or IP address of your IBM i system) 60 | 61 | Enter your password as requested. You should now be connected! 62 | 63 | **Gotcha!!** 64 | 65 | If your IBM i user profile is longer than 8 characters long, and you are 66 | running IBM i 7.3 or earlier, you need to remove this restriction by way 67 | of the `PASE_USRGRP_LIMITED` environment variable. The easy way to do this 68 | is to have your system administrator set it system-wide: 69 | 70 | ```lisp 71 | ADDENVVAR ENVVAR(PASE_USRGRP_LIMITED) VALUE('N') LEVEL(*SYS) 72 | ``` 73 | 74 | ## Step 3: Create your home directory 75 | 76 | From your SSH session, run the following command: 77 | 78 | ```bash 79 | mkdir -p $HOME 80 | ``` 81 | 82 | Now, verify this was successful by running the following commands: 83 | 84 | ```bash 85 | cd $HOME 86 | pwd 87 | ``` 88 | 89 | The output of the `pwd` command should match your home directory as configured 90 | in your IBM i user profile (typically `/home/USRPRF`). 91 | 92 | ## Step 4: Change your default shell to `bash` 93 | 94 | The default shell program on IBM i is very deficient as an operating environment. 95 | It is highly recommended that you use bash by following 96 | [these steps](../troubleshooting/SETTING_BASH.md), which essentially boils down to 97 | running this command in your SSH session: 98 | 99 | ```bash 100 | /QOpenSys/pkgs/bin/chsh -s /QOpenSys/pkgs/bin/bash 101 | ``` 102 | 103 | (there is also an SQL approach in the docs, if that is preferred) 104 | 105 | When complete, exit your SSH session by typing `exit` and reconnecting as you did 106 | earlier. You should now be running bash, as evidenced by a command prompt that 107 | indicates a bash version (for instance, `-bash-5.1`). 108 | 109 | ## Step 5: Configure your `PATH` 110 | 111 | In order for your woking environment to find the open source toolset, you need 112 | to set up your `PATH` (environment variable) appropriately. The `PATH` is 113 | often considered analogous to a library list. Instead of libraries, though, 114 | it contains a list of directories to be searched for UNIX-style commands, as 115 | would be run in a PASE environment (SSH) on IBM i. 116 | 117 | Configuration of `PATH` is documented in 118 | [these steps](../troubleshooting/SETTING_PATH.md), which boils down to 119 | running this sequence of commands in your SSH session: 120 | 121 | ```bash 122 | touch $HOME/.profile 123 | setccsid 1208 $HOME/.profile 124 | echo 'PATH=/QOpenSys/pkgs/bin:$PATH' >> $HOME/.profile 125 | echo 'export PATH' >> $HOME/.profile 126 | ``` 127 | 128 | When complete, exit your SSH session by typing `exit` and reconnecting as you did 129 | earlier. Your environment should now have `PATH` set up properly. To verify this, 130 | run the following command: 131 | 132 | ```bash 133 | which bash 134 | ``` 135 | 136 | Output should be: 137 | 138 | ```matlab 139 | /QOpenSys/pkgs/bin/bash 140 | ``` 141 | 142 | ## Step 6 (optional): Configure password-less login 143 | 144 | Would you like to `ssh` into a system without typing your password? If so, 145 | you can use a public/private key pair to authenticate to the system. 146 | 147 | ### Step 6a: Generate a key pair 148 | 149 | The first thing you need to do is generate a key pair. PuTTY ships a "PuTTYgen" 150 | utility to do this. For other clients, run the following command from your 151 | terminal, and respond appropriately to any questions it asks: 152 | 153 | ``` 154 | ssh-keygen 155 | ``` 156 | 157 | **IMPORTANT NOTE**: A key pair consists of a public key and a private key. 158 | Never, under **any** circumstances, share your private key with another 159 | entity. It should exist on your local system only. 160 | 161 | ### Step 6b: copy public key to server 162 | 163 | Next, you can copy your public key to the IBM i server by running the following 164 | command from your terminal: 165 | 166 | ```bash 167 | ssh-copy-id user@host 168 | ``` 169 | 170 | If, for some reason you don't have the `ssh-copy-id` command, or if you used 171 | PuTTYgen to generate your key pair, you can manually copy the key to the server. 172 | To do so, you can first create the server-side file by running the following: 173 | 174 | ``` 175 | mkdir -p $HOME/.ssh 176 | touch $HOME/.ssh/authorized_keys 177 | ``` 178 | 179 | The `authorized_keys` file will store your public keys for any clients wishing 180 | to connect with key-based authentication. After this file is created, you can 181 | add your public key. To do so, locate the file on your PC with the public key. 182 | This is usually stored in a file named "id_algorithm.pub", where "algorithm" 183 | is the key pair algorithm. Most commonly, the file name is `id_rsa.pub`. If 184 | using PuTTYgen, the user interface shows a text field labeled "public key 185 | for pasting into OpenSSH authorized_keys file:". You can copy/paste that into 186 | a file for use with the next step. 187 | 188 | Once you've located your public key file, you can place it into your home 189 | directory on IBM i, open an SSH session and run (substitute file name 190 | as needed, this example assumes `id_rsa.pub`): 191 | 192 | ```bash 193 | cat id_rsa.pub >> $HOME/.ssh/authorized_keys 194 | rm id_rsa.pub 195 | ``` 196 | 197 | ### Step 6c: Fix filesystem permissions 198 | 199 | OpenSSH strictly enforces that the permissions of the necessary directories 200 | and files are set in a secure manner. It will not work unless the permissions 201 | are set correctly. To fix them up, run the following commands in your SSH 202 | terminal: 203 | 204 | ```bash 205 | chown "$(/QOpenSys/usr/bin/id -u -n)" $HOME 206 | chown -R "$(/QOpenSys/usr/bin/id -u -n)" $HOME/.ssh 207 | chmod 0755 $HOME 208 | chmod 0700 $HOME/.ssh 209 | chmod 0644 $HOME/.ssh/authorized_keys 210 | ``` 211 | 212 | ### Step 6d: Verify password-less login 213 | 214 | Sign out of your SSH session. Sign on again, as you did before (for instance, 215 | `ssh user@host`). You should now be able to log in without a password! 216 | 217 | ## Having problems? 218 | 219 | If you're having any problems, feel free to reach out to the various community 220 | and support resources listed in [the IBM i Open Source resources](http://ibm.biz/ibmioss). 221 | 222 | ## Want an even more robust experience? 223 | 224 | Check out [the dotfiles project](https://github.com/jbh/ibmi-dotfiles), which 225 | provides more advanced environment customizations for the IBM i. This is especially 226 | useful for Linux users on IBM i. 227 | -------------------------------------------------------------------------------- /yum/3RD_PARTY_REPOS.md: -------------------------------------------------------------------------------- 1 | # Third-party (non-IBM) repositories 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | The repositories listed on this page are not owned, managed, or supported by 8 | IBM. However, the repositories have been inspected and the software 9 | generally seems to be built with IBM-approved conventions for existing well in 10 | the IBM-delivered open source ecosystem. 11 | 12 | ## Installation instructions 13 | 14 | First the `yum-utils` package should be installed. This provides the 15 | `yum-config-manager` utility, which mades it easy to add new repositories, as 16 | well as enable or disable existing repositories. 17 | 18 | ## Repository List 19 | 20 | ### PHP 21 | 22 | Several PHP distributions are available. See [http://ibm.biz/ibmi-php](http://ibm.biz/ibmi-php) 23 | 24 | ### OpenMax 25 | 26 | **Brought to you by:** [Massimo Fantin](https://twitter.com/massimofantin) 27 | 28 | **Software offered:** A large collection of open source packages, including Postgresql, 29 | Ghostscript, Postfix , rddtool etc etc 30 | 31 | ### The i Doctor 32 | 33 | **Brought to you by:** Jack Woehr 34 | 35 | **Software offered:** lynx-dev (limited capabilities, for instance no https support). 36 | schily-tools (cdrecord, mkisofs, etc.) 37 | 38 | **Install**: `yum-config-manager --add-repo http://www.the-i-doctor.com/oss/repo/the-i-doctor.repo` 39 | 40 | ### QSECOFR 41 | 42 | **Brought to you by:** Yvan Janssens 43 | 44 | **Software offered:** Mono on i and various Open Source software for which fixes 45 | have been accepted upstream to enable them to run on i. 46 | 47 | **Install**: `yum-config-manager --add-repo http://repo.qseco.fr/qsecofr.repo` 48 | 49 | ### SoBored 50 | 51 | **Brought to you by:** Josh Hall 52 | 53 | **Software offered:** [ibmi-dotfiles](https://github.com/jbh/ibmi-dotfiles) 54 | 55 | **Install**: `yum-config-manager --add-repo http://rpms.sobo.red/ibmi/` 56 | -------------------------------------------------------------------------------- /yum/IBM_REPOS.md: -------------------------------------------------------------------------------- 1 | # IBM Repositories 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | IBM provides a set of repositories to use with yum. Previously, there was one repo called 8 | "ibm" pointing [here](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo). 9 | Since the end of 2021, this repo has been deprecated and obsoleted by the repos provided 10 | by the ibmi-repos package. 11 | 12 | The ibmi-repos package is now required by yum and contains two repos: 13 | 14 | - ibmi-release 15 | - ibmi-base 16 | 17 | The ibmi-release repo points to a release-specific directory. Depending on what IBM i 18 | version you are running, the repo will dynamically determine the correct path use. This 19 | repo will contain rpms which are applicable to that specific release. 20 | 21 | The ibmi-base repo will contain packages which are applicable to all releases supported by 22 | that repo (ie. there's a minimum release). Over time, this repo will change as older IBM i 23 | releases go out of support and a new minimum release base repo is created. 24 | 25 | Since August 18 2022, IBM i 7.3+ systems will see an ibmi-repos update in the ibmi-release 26 | repo. This update changes the ibmi-base repo URL from the old [7.2+ repo](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo) 27 | to the new [7.3+ repo](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo-base-7.3/). 28 | 29 | IBM i 7.2 users are unaffected, since the 7.2 ibmi-release repo does not have the update. 30 | Users still on IBM i 7.2 can continue using the old repo (and systems can still be bootstrapped 31 | using the [7.2 bootstrap](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/bootstrap-7.2/)), 32 | however there will be no more updates to 7.2 packages - security or otherwise. Users still on 33 | IBM i 7.2 are encouraged to update to IBM i 7.3 or newer, supported release. 34 | 35 | ## Transition 36 | 37 | Since December 2021, any system using a current bootstrap will start with the ibmi-repos 38 | package installed. Any system set up using a prior bootstrap will not have the ibmi-repos 39 | package and will instead have an ibm.repo file. See the FAQs below for how to deal with 40 | the old repo file. 41 | 42 | ## FAQs 43 | 44 | ### Why are you making this change? 45 | 46 | By providing the IBM repos in an rpm, it allows us to push out updates to our repo files using the same yum update mechanism. 47 | 48 | 49 | Some examples of changes may include: 50 | 51 | - The path to repo needs to change 52 | - The protocol changes (FTP -> HTTPS) 53 | - We start signing our repo metadata 54 | - etc 55 | 56 | 57 | ### Why are you adding a new ibm-base repo instead of updating the existing repo? 58 | 59 | Because ibm.repo is not tracked by rpm, it becomes tricky to take over ownership of the file by rpm while preventing any local modifications from being overwritten while also being a seamless transition for users. By providing a new repo file, all users will immediately get access to the new repo because there are no conflicts with existing repo files. This also allowed us to give the repo a more meaningful name. 60 | 61 | ### What if I've deleted or disabled the ibm repo file? 62 | 63 | Because the ibmi-repos package ships new repo files, the existing repo file is unaffected. However, the new repos _will_ be enabled by default. You can disable them using `yum-config-manager --disable ibmi-base ibmi-release` 64 | 65 | Note that the new repo files are shipped with `skip_if_unavailable=1` set. This means that if you've disabled the ibm repo because your system does not have internet access, these repo files will not cause yum failures, but only warnings like 66 | 67 | ```text 68 | https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/repo-7.4/repodata/repomd.xml: [Errno 14] HTTPS Error 404 - Not Found 69 | Trying other mirror. 70 | ``` 71 | 72 | ### What if I've made changes to the existing ibm repo file? 73 | 74 | Because the ibmi-repos package ships new repo files, the existing repo file is unaffected. It is recommended to rename the ibm.repo and disable the new repos with `yum-config-manager --disable ibmi-base ibmi-release` or manually apply your changes to the new repo files. 75 | 76 | ### What happens if I make changes to the new ibmi-base or ibmi-release repos? 77 | 78 | Both of these files are marked as special config files inside rpm, which means that rpm will detect if they've been modified and if so it **will not** overwrite them. Instead, you will see a message from yum: 79 | 80 | ```text 81 | warning: /QOpenSys/etc/yum/repos.d/ibmi-base.repo created as /QOpenSys/etc/yum/repos.d/ibmi-base.repo.rpmnew 82 | ``` 83 | 84 | It is up to you to look at the .rpmnew file to see what changes have been made and, if applicable, adjust the repo file accordingly. 85 | 86 | ### You said ibm and ibmi-base point to the same location; will that cause any problems? 87 | 88 | There should not be any problems with both ibm and ibmi-base pointing to the same location. Yum will see two repos providing the same packages and will pick one when it goes to install updates. 89 | 90 | Though there should be no problems having them both enabled, it's recommended that you disable the ibm repo using `yum-config-manager --disable ibm`. Once you have verified yum continues to work without it enabled, you can remove it using `rm /QOpenSys/etc/yum/repos.d/ibm.repo`. 91 | 92 | ### What should I do with the existing ibm repo file? 93 | 94 | This repo is no longer needed as the ibmi-base repo supersedes it. It's recommended that you disable the ibm repo using `yum-config-manager --disable ibm`. Once you have verified yum continues to work without it enabled, you can remove it using `rm /QOpenSys/etc/yum/repos.d/ibm.repo`. 95 | 96 | ### Can I remove the ibmi-repos package? 97 | 98 | No, yum has been made to depend on it and yum will prevent removing itself. 99 | 100 | If you do not want these new repo files to be enabled, you can disable them using `yum-config-manager --disable ibmi-base ibmi-release`. 101 | 102 | ### Will the ACS clone tool work with the new repos? 103 | 104 | Yes, the ACS clone tool should work with any repository. 105 | 106 | ### Will the ACS yum proxy work with the new repo? 107 | 108 | Yes, the ACS yum proxy should work with all HTTP-based repositories. 109 | 110 | -------------------------------------------------------------------------------- /yum/OPENSSL3_MIGRATION.md: -------------------------------------------------------------------------------- 1 | # OpenSSL 3.0 Migration 2 | 3 | On August 12, 2024 IBM has shipped out updates to various packages using 4 | OpenSSL. These updates switches the version of OpenSSL these packages use to 5 | use OpenSSL 3.0 instead of OpenSSL 1.1.1 (which is no longer supported by the 6 | OpenSSL project). 7 | 8 | ## Upgrade Risk 9 | 10 | This change brings potential risk of application crash if OpenSSL 1.1.1 and 11 | OpenSSL 3.0 are loaded in to the same process and the software is built with 12 | runtime linking enabled (the default in the open source ecosystem). This can 13 | happen even for software that does not use OpenSSL itself, but relies on other 14 | packages which do use OpenSSL. For example, Python's `ssl` package directly 15 | loads OpenSSL and the PyCurl package _indirectly_ loads OpenSSL through the 16 | Curl library, which links to it. If the `ssl` package is linked to one version 17 | of OpenSSL and the Curl library gets updated to use a different version of 18 | OpenSSL, this could cause the software to crash. 19 | 20 | ## Mitigations 21 | 22 | The good news is that changes have been put in place to mitigate these problems 23 | as much as possible. Software provided by IBM has been modified to use 24 | different compilation options to disable runtime linking for software using 25 | OpenSSL (either directly or indirectly). By disabling runtime linking, this 26 | allows OpenSSL 1.1.1 and OpenSSL 3.0 to coexist in the same process. In 27 | addition, rules have been added to various packages such as Curl, Python, etc 28 | that will prevent certain packages being upgraded unless packages requiring 29 | mitigation have been updated. 30 | 31 | It is still recommended to update all affected packages so that they use the 32 | supported OpenSSL 3.0, but there should be no issues for mismatched 33 | environments where only some of them are updated and some still use older 34 | OpenSSL versions. 35 | 36 | ## Diagnosis 37 | 38 | Here's how to diagnose the issue if you happen to run in to this problem. 39 | Again, all IBM software _should_ be mitigated however third-party software may 40 | not be mitigated yet. The typical result will be the following generic error 41 | message: 42 | 43 | ```text 44 | Segmentation fault (core dumped) 45 | ``` 46 | 47 | A typical backtrace might look something like this: 48 | 49 | ```text 50 | #0 0x090000000c2e9cfc in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.1.1(shr_64.o) 51 | #1 0x090000000c387018 in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.1.1(shr_64.o) 52 | #2 0x090000000c387018 in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.1.1(shr_64.o) 53 | #3 0x090000000c8e62d4 in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.3(shr_64.o) 54 | #4 0x090000000c8e65c4 in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.3(shr_64.o) 55 | #5 0x090000000c8bf718 in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.3(shr_64.o) 56 | #6 0x090000000c8bfcd8 in ?? () from /QOpenSys/pkgs/lib/libcrypto.so.3(shr_64.o) 57 | #7 0x090000000c7ca654 in ?? () from /QOpenSys/pkgs/lib/libssl.so.3(shr_64.o) 58 | #8 0x090000000c798c0c in ?? () from /QOpenSys/pkgs/lib/libssl.so.3(shr_64.o) 59 | #9 0x090000000c798ff0 in ?? () from /QOpenSys/pkgs/lib/libssl.so.3(shr_64.o) 60 | #10 0x090000000c6d490c in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 61 | #11 0x090000000c6d5ab8 in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 62 | #12 0x090000000c6cd9e8 in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 63 | #13 0x090000000c6b8fec in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 64 | #14 0x090000000c6c7a60 in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 65 | #15 0x090000000c6b8fec in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 66 | #16 0x090000000c73adec in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 67 | #17 0x090000000c6b9ff4 in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 68 | #18 0x090000000c6b0f9c in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 69 | #19 0x090000000c6b27c8 in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 70 | #20 0x090000000c6ab204 in ?? () from /QOpenSys/pkgs/lib/libcurl.so.4(shr_64.o) 71 | ``` 72 | 73 | Here, a function at frame 3 is in libcrypto.so.3 and then at frame 2, is in 74 | libcrypto.so.1.1. So somehow an OpenSSL 3 function is inadvertently calling an 75 | OpenSSL 1.1.1 function, causing a segmentation fault due to improperly 76 | initialized memory or binary incompatibilities between version 3.0 and 1.1.1 of 77 | OpenSSL. Luckily, this _specific_ problem shown from Python should no longer be 78 | an issue. 79 | 80 | ## Third Party Software 81 | 82 | There is still some risk for third party applications. Please consult with your 83 | third party application vendors to ensure that their software is rebuilt with 84 | OpenSSL 3.0 and/or is disabling runtime linking. 85 | 86 | Seiden Group has a version of PHP available which disables runtime linking. 87 | -------------------------------------------------------------------------------- /yum/README.md: -------------------------------------------------------------------------------- 1 | # RPM pile for IBM i releases in standard support 2 | 3 | ```{toctree} 4 | :maxdepth: 1 5 | ``` 6 | 7 | ## General Information 8 | 9 | Much of the open source technology available in the 5733-OPS product is now 10 | available in RPM form! This allows for a more seamless experience for those 11 | needing to install, manage, or use open source technologies. You can use the 12 | "yum" package manager to see the entire list of what packages are available. 13 | 14 | ### Notable deliverables 15 | 16 | - Node.js 17 | - Python 3.6 18 | - The 'less' utility 19 | - git 20 | - The 'updatedb' and 'locate' utilities (in the 'findutils' package) 21 | - GCC 6.3.0 and many development tools such as automake, autoconf, m4, libtool, 22 | etc. 23 | - GNU versions of many common utilities such as ls, grep, sed, awk..... 24 | - GNU Nano 25 | - many, many more things..... 26 | 27 | ## Installation 28 | 29 | Once you have `yum` installed, you can install, remove, and upgrade rpms easily. 30 | `yum` is even able to update and install new versions of itself! But how do you 31 | install `yum` if you don't have `yum` installed? We have a Catch-22! To get 32 | around this loop, we have provided a bootstrap installer which installs and 33 | configures yum via a different mechanism which has just enough to get `yum` and 34 | installed and working. As said before, once `yum` is installed it can update 35 | itself, so this bootstrap process is only needed once! 36 | 37 | *NOTE: Don't forget to read the Usage Notes below. They are very important!* 38 | 39 | ### Installing with Access Client Solutions (ACS) 40 | 41 | *NOTE: This currently requires that your PC have direct HTTPS access to the 42 | public IBM file server. If for some reason, you cannot access external sites via 43 | HTTPS, refer to steps in "Offline Install Instructions (without ACS)".* 44 | 45 | *You will also need SSH connectivity from your PC to the IBM i system. Be sure 46 | to have the SSH daemon running on IBM i (`STRTCPSVR *SSHD`).* 47 | 48 | *This technique does not require external Internet access from your IBM i 49 | system..* 50 | 51 | - Download the latest release of Access Client Solutions 52 | 53 | - Access the Open Source Package Management Interface through the "Tools" Menu 54 | of ACS 55 | 56 | - For more information, see [this Technote](http://www-01.ibm.com/support/docview.wss?uid=nas8N1022619) 57 | 58 | ### Online Install Instructions (without ACS Open Source Management Tool) 59 | 60 | *NOTE: This requires that your IBM i have direct FTP access to the public IBM 61 | file server from your IBM i system. Many companies now block FTP access. If that 62 | is the case, refer to steps in "Offline Install Instructions (without ACS)".* 63 | 64 | - Download [bootstrap.sql](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/bootstrap.sql) 65 | to your PC 66 | 67 | - Open ACS Run SQL Scripts and connect to the IBM i you want to install to 68 | 69 | - Open bootstrap.sql in your Run SQL Scripts window 70 | 71 | - Execute "Run All" via Toolbar, Menu option, or Ctrl-Shift-A 72 | 73 | - If the result is "Bootstrapping Successful" you're all good. If not, consult 74 | /tmp/bootstrap.log. 75 | 76 | ### Offline Install Instructions (without ACS) 77 | 78 | - Download [bootstrap.sh](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/bootstrap.sh) 79 | and [bootstrap.tar.Z](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/bootstrap.tar.Z) 80 | to your PC 81 | 82 | - Transfer these two files to the `/tmp` directory on your IBM i system (via 83 | FTP, mapped network drive, scp, etc). *Make sure to transfer them in binary.* 84 | 85 | - From a 5250 terminal run the following. 86 | 87 | ```text 88 | QSH CMD('exec /QOpenSys/usr/bin/ksh -c "/QOpenSys/usr/bin/ksh /tmp/bootstrap.sh > /tmp/bootstrap.log 2>&1"') 89 | ``` 90 | 91 | - If you see message QSH005: "Command ended normally with exit status 0" in the 92 | job log you're all good. If not, consult `/tmp/bootstrap.log`. 93 | 94 | ### IBM i 7.1 Install Instructions (experimental; not supported!) 95 | 96 | - Download IBM i 7.1 version of [bootstrap.sh](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/bootstrap-7.1/bootstrap.sh) 97 | and [bootstrap.tar.Z](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/bootstrap-7.1/bootstrap.tar.Z) 98 | to your PC 99 | 100 | - Transfer these two files to the `/tmp` directory on your IBM i system (via 101 | FTP, mapped network drive, scp, etc). *Make sure to transfer them in binary.* 102 | 103 | - From a 5250 terminal run the following. 104 | 105 | ```text 106 | QSH CMD('exec /QOpenSys/usr/bin/ksh -c "/QOpenSys/usr/bin/ksh /tmp/bootstrap.sh > /tmp/bootstrap.log 2>&1"') 107 | ``` 108 | 109 | - If you see message QSH005: "Command ended normally with exit status 0" in the 110 | job log you're all good. If not, consult `/tmp/bootstrap.log`. 111 | 112 | ## Switching from FTP to HTTP(S) 113 | 114 | The original bootstrap used FTP to connect to the public IBM file server. This 115 | server has now had HTTP and HTTPS enabled, so you can switch to using HTTP if 116 | you prefer. This is especially useful if your corporate firewall rules disallow 117 | unsecured FTP (which many do). 118 | 119 | The easiest way to do so is to download the new [repo file](https://public.dhe.ibm.com/software/ibmi/products/pase/rpms/ibm.repo) 120 | and replace the one at `/QOpenSys/etc/yum/repos.d/ibm.repo`. There are numerous 121 | ways to do this, but perhaps the easiest is with `curl`: 122 | 123 | ```bash 124 | curl http://public.dhe.ibm.com/software/ibmi/products/pase/rpms/ibm.repo > /QOpenSys/etc/yum/repos.d/ibm.repo 125 | ``` 126 | 127 | *NOTE: If you download it another way, make sure to transfer it to the IBM i 128 | system in binary or ASCII modes.* 129 | 130 | If you are switching to HTTPS (recommended), first install the CA certificates 131 | package to avoid CURL SSL errors, and then change the protocol in the repo file 132 | from HTTP to HTTPS (the original file will be saved with suffix "_backup"): 133 | 134 | ```bash 135 | # Install SSL CA certificates 136 | yum install ca-certificates-mozilla 137 | # Install sed tool from repository 138 | yum install sed-gnu 139 | # Switch the protocol to https 140 | /QOpenSys/pkgs/bin/sed --in-place='_backup' 's/http:/https:/' /QOpenSys/etc/yum/repos.d/ibm.repo 141 | ``` 142 | 143 | ## Using yum on an IBM i system without internet access 144 | 145 | If your IBM i system does not have access to the internet, yum will not be able 146 | to connect to the public IBM file server to download rpms. There are a number of 147 | options to overcome this limitation: 148 | 149 | ### 1. Use a proxy 150 | 151 | If you have a proxy server available to you on your local intranet, yum can be 152 | configured to use it. Under the `main` section in `/QOpenSys/etc/yum/yum.conf` 153 | you can set `proxy`, `proxy_username`, and `proxy_password` options. eg. 154 | 155 | ```ini 156 | [main] 157 | proxy=http://proxy.mycompany.example.com:1234 158 | proxy_username=user_name 159 | proxy_password=passw0rd 160 | ``` 161 | 162 | ### 2. Create a local repository mirror 163 | 164 | If you want to keep a local cache of the repository, you can use the `reposync` 165 | and `createrepo` commands to create a complete copy of the remote repo. You'll 166 | need to do this from a system which does have external (outbound) network 167 | access. It can be on any OS which has the above tools available (on IBM i 168 | `yum install yum-utils createrepo` to install them). 169 | 170 | ```shell 171 | reposync -p /path/to/repo/root -r ibm 172 | createrepo /path/to/repo/root/ibm 173 | ``` 174 | 175 | If you are running this from a non-IBM i system, you will need to run the 176 | `reposync` command twice, specifying different `-a` parameters to download all 177 | the different architecture packages, eg. 178 | 179 | ```shell 180 | reposync -a ppc64 -p /path/to/repo/root -r ibm 181 | reposync -a fat -p /path/to/repo/root -r ibm 182 | createrepo /path/to/repo/root/ibm 183 | ``` 184 | 185 | Once this is done, you can share `/path/to/repo/root/ibm` on your local network 186 | using an HTTP server. This will be your new IBM i repository URL, so change the 187 | URL in the `ibm.repo` file to match. 188 | 189 | Now that you are downloading the files through a mirror, you will need to keep 190 | the mirror in sync. Setting up a periodic task (via scheduled job or `cron`) to 191 | run the above commands will make this easy, but you can also do it manually as 192 | well. 193 | 194 | ## Must-know Usage Notes!!! (READ THIS AFTER YOU INSTALL) 195 | 196 | All software provided by the RPMs will install in to the `/QOpenSys/pkgs` 197 | prefix. You can fully qualify the path to the program or you can add 198 | `/QOpenSys/pkgs/bin` to your `PATH` to use the software. There are currently no 199 | plans to add symlinks in to `/QOpenSys/usr/bin` or `/QOpenSys/usr/lib`, though 200 | you can certainly do so if you like. 201 | 202 | ### Fully Qualifying 203 | 204 | ```sh 205 | /QOpenSys/pkgs/bin/bash --version 206 | GNU bash, version 4.4.12(1)-release (powerpc-ibm-os400) 207 | Copyright (C) 2016 Free Software Foundation, Inc. 208 | License GPLv3+: GNU GPL version 3 or later 209 | 210 | This is free software; you are free to change and redistribute it. 211 | There is NO WARRANTY, to the extent permitted by law. 212 | ``` 213 | 214 | ### Adjusting your PATH 215 | 216 | ```sh 217 | PATH=/QOpenSys/pkgs/bin:$PATH 218 | export PATH 219 | 220 | bash --version 221 | GNU bash, version 4.4.12(1)-release (powerpc-ibm-os400) 222 | Copyright (C) 2016 Free Software Foundation, Inc. 223 | License GPLv3+: GNU GPL version 3 or later 224 | 225 | This is free software; you are free to change and redistribute it. 226 | There is NO WARRANTY, to the extent permitted by law. 227 | ``` 228 | 229 | If you want to make your `PATH` setting permanent, add the above line to your 230 | `$HOME/.profile`. You can do this easily (from a shell) like so. 231 | 232 | ```sh 233 | echo 'PATH=/QOpenSys/pkgs/bin:$PATH' >> $HOME/.profile 234 | echo 'export PATH' >> $HOME/.profile 235 | ``` 236 | 237 | ## Installing additional software 238 | 239 | ### Using Access Client Solutions (ACS) 240 | 241 | [This Technote](http://www-01.ibm.com/support/docview.wss?uid=nas8N1022619) 242 | demonstrates how to use ACS to perform simple package management tasks such as 243 | adding, removing, or upgrading software. 244 | 245 | ### Yum cheat sheet 246 | 247 | If you don't know how to use yum, Red Hat has a handy "cheat sheet" available 248 | [here](https://access.redhat.com/sites/default/files/attachments/rh_yum_cheatsheet_1214_jcs_print-1.pdf). 249 | 250 | ### Common commands 251 | 252 | - Install a package: `yum install ` 253 | - Remove a package: `yum remove ` 254 | - Search for a package: `yum search ` 255 | - List installed packages: `yum list installed` 256 | - List available packages: `yum list available` 257 | - List all packages: `yum list all` 258 | 259 | ### Installing Python 3 and some useful Python packages 260 | 261 | ```shell 262 | yum install python3-pip python3-ibm_db python3-itoolkit 263 | ``` 264 | 265 | ### Installing Python 3 Machine Learning packages 266 | 267 | ```shell 268 | yum install python3-numpy python3-pandas python3-scikit-learn python3-scipy 269 | ``` 270 | 271 | ### Installing Node.js 272 | 273 | ```sh 274 | yum install nodejs10 275 | ``` 276 | 277 | ### Installing GCC and development tools 278 | 279 | ```sh 280 | yum group install "Development tools" 281 | ``` 282 | 283 | ### Using a chroot 284 | 285 | If you'd like to install in to a chroot, you can use the scripts from 286 | [ibmichroot](https://github.com/IBM/ibmichroot) to set up a chroot using the 287 | `chroot_minimal.lst` and extract the bootstrap to there. 288 | 289 | If you install to the root of the OS, you can use rpm to help install chroots. 290 | Use the `chroot_minimal.lst` to set up the chroot and then use the 291 | `--installroot` option on rpm to install the rpm in to that chroot. 292 | 293 | ```sh 294 | yum --installroot= install 295 | ``` 296 | 297 | The following dummy packages exist to satisfy RPM dependencies inside the 298 | chroot. 299 | 300 | ```sh 301 | pase-libs-dummy-7.1-0.ibmi7.1.fat.rpm 302 | coreutils-pase-dummy-7.1-0.ibmi7.1.ppc.rpm 303 | ``` 304 | 305 | ## Troubleshooting 306 | 307 | Having issues? Please check out the [troubleshooting guide](../troubleshooting/README.md). 308 | 309 | ## FAQ 310 | 311 | ### What if I run in to issues? 312 | 313 | See **Troubleshooting** section above. 314 | 315 | ### How do I get support for open source on IBM i? 316 | 317 | Open source support is available through community channels or an IBM premium 318 | support offering. See 319 | 320 | ### Is 5733-OPS required in order to install the RPM-based deliverables? 321 | 322 | No. 5733-OPS does not need to be installed. 323 | 324 | ### When will tools and language runtimes be 64-bit enabled? 325 | 326 | Most of the software available in RPM form is 64-bit, including the Python and 327 | Node.js runtimes 328 | 329 | ### Will 5733-OPS be updated to ship Node.js version 8, Python 3.6, or other goodies that are currently in RPM form only? 330 | 331 | There are currently no plans to deliver these packages in the 5733-OPS 332 | installable product. If you have a business need for such, please submit an RFE 333 | with your justification. 334 | 335 | ### Is this the same thing as Perzl.org or other RPM's I have heard of (or used) in the past? 336 | 337 | No. These RPM's are not AIX RPM's. They are IBM i RPMs shipping IBM i software. 338 | Built on IBM i, for IBM i. 339 | 340 | ### What if I am on an IBM i release no longer in standard support? 341 | 342 | IBM strives to provide community open source software packages for IBM i 343 | releases in standard support. Packages (including the initial installer) that 344 | are delivered for any IBM i release no longer in standard support may be rebuilt 345 | without notice, in an effort to leverage the latest technology for IBM i 346 | customers. 347 | 348 | ### IBM repositories 349 | 350 | Information on IBM-provided repositories can be found [here](IBM_REPOS.md). 351 | 352 | ### Third-party (non-IBM) repositories 353 | 354 | Information on third-party repositories can be found [here](3RD_PARTY_REPOS.md). 355 | --------------------------------------------------------------------------------